Planning

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

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.