/planning

name: planning
description: |
  Use when writing an execution plan or a decision RFC: task decomposition, context
  references, validation levels, risk-based testing, ADR format, plan completeness gate,
  and functionality flow mapping.
allowed-tools: Read Write Edit Grep Glob LSP
user-invocable: false

Planning

Distill plans into durable, buildable artifacts. A plan is a contract, not a brainstorm.

Reference Files

• `references/live-verification-strategy.md` — when and how to plan live/production verification; load when the request calls for production-like confidence (real integrations, deployment, live data) or any task's validation level is Live

Bite-Sized Task Granularity

Each task must fit a single fresh context window: one builder can read the referenced files, implement, and test it without compaction. A task that outlives its window gets finished by a degraded agent — split it. Signs a task is too big: "and then...", multiple unrelated files, multiple test scenarios, more than 3 sub-steps.

**Test per task:** Every task must have at least one test that verifies its completion. If you can't name the test, the task isn't specific enough.

Plan Document Header

# [Feature Name] Plan

## Metadata
- Created: [date]
- Status: [draft|approved|in-progress|complete]
- Verification Rigor: [standard|critical_path]
- Plan Mode: [direct|execution_plan|decision_rfc]

## Agreement Snapshot
- **Goal:** [one sentence]
- **Constraints:** [list]
- **In Scope:** [list]
- **Out of Scope:** [list]
- **Open Decisions:** [list or "none"]

Task Structure

Each task in the plan:

### Task N: [Component Name]
**Objective:** [what this task achieves]
**Files/Surfaces:** [exact files to create/modify]
**Dependencies:** [previous task IDs or "none"]
**Allowed Scope:** [what's in bounds]
**Out-of-Scope Drift:** [what would be scope creep]
**Expected Artifacts:** [what this produces]
**Required Checks:** [tests/verification needed]
**Checkpoint Type:** [none|human_verify|decision|human_action]
**Exit Criteria:** [how to know this task is done]

**Consumes:** [exact signatures used from earlier phases — verbatim]
**Produces:** [exact names later phases rely on — verbatim]

If no Consumes/Produces: write `Consumes: none` / `Produces: none` explicitly.

Context References Section (MUST READ before planning)

List files the builder MUST read before starting:

• **Patterns to follow:** existing components/modules that demonstrate the project's conventions
• **Configuration files:** tsconfig, package.json, .eslintrc, etc.
• **Related documentation:** API docs, architecture docs, existing ADRs
• **Compounded knowledge:** if `docs/solutions/` exists, check it for prior write-ups on the same problem category before designing from scratch — a past debugging/architecture lesson may already explain the constraint you're about to rediscover

**Distillation Rule:** Reference files by path with a one-line reason. Do not paste contents. The next agent reads the file, not your summary of it.

**Durability-Horizon Rule:** For each piece of the plan, state how long it's expected to last: "session-only" (throwaway), "near-term-refactor" (refactor likely), "stable" (architectural). This determines how much effort to spend on abstraction.

Validation Levels

The canonical Validation Levels table (Deterministic / Probabilistic / Manual / **Live**) is defined once in `cc10x:verification` under `## Validation Levels` — do not restate it here.

Planner-specific mapping: every task must state its validation level. If manual, state the checklist. If deterministic, state the command. If probabilistic, state the flake rate and retry policy. If live, state the harness command and add a `### Live Verification Strategy` section (see `references/live-verification-strategy.md`).

Plan Completeness Gate (MANDATORY — before save)

Scan the plan against these 10 checks. Fix inline.

1. Every task has a test that verifies completion 2. Every task lists exact file paths (not "the auth module" — `src/auth/handler.ts`). Exact paths are safe here because a plan is executed immediately; a spec that lives for weeks would omit them. 3. Every task has exit criteria (not "done" — "test passes, build succeeds, type-check clean") 4. Dependencies are explicit (task IDs, not "after the API stuff") 5. Scope drift is named (what would pull this task off-track) 6. Consumes/Produces are verbatim-matched across phases (no spelling drift) 7. Validation level is stated for every task 8. Risk-based testing matrix is complete (see below) 9. No placeholders/TBD — every section holds a real decision 10. Open decisions are listed (not hidden in prose)

Risk-Based Testing Matrix

| Risk | Probability | Impact | Test Required | |------|------------|--------|---------------| | [what could go wrong] | [low/med/high] | [low/med/high] | [test name or "manual: checklist"] |

Map Probability × Impact directly to the test requirement: high/high or high/med (either order) → deterministic test required; med/med → deterministic or probabilistic with stated flake policy; anything involving a low → manual checklist acceptable. When unsure between two cells, take the stricter one.

Test-Seam Selection Discipline

Choose the seam where the test attaches:

• **Unit seam:** pure function, no dependencies — fastest, most stable
• **Integration seam:** module boundary, real dependencies for adjacent layers — catches wiring
• **E2E seam:** user flow, all real dependencies — catches interaction bugs

Prefer the highest seam that still covers the risk. A unit test that doesn't exercise the real code path is a shallow test. An E2E test for a pure function is overkill.

**Prefer existing seams to new ones.** The fewer seams across the codebase, the better — the ideal number is one. If new seams are needed, propose them at the highest point you can.

**Record proposed seams in each phase.** Each phase's plan carries a `### Te