planning-patterns

name: planning-patterns description: "Internal cc10x skill, loaded by the planner. Use when producing a comprehensive implementation plan with phases, exit criteria, risks, and verifiable acceptance scenarios." allowed-tools: Read Grep Glob LSP user-invocable: false

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for the codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Plans are prompts. The plan will be consumed by an AI agent with zero prior context. Write it as you would write a prompt: specific, complete, unambiguous. If a different agent could misinterpret a step, the step is underspecified.

Assume they are a skilled developer, but know almost nothing about the toolset or problem domain. Assume they don't know good test design very well.

Core principle: Plans must be executable without asking questions.

The Iron Law

NO VAGUE STEPS - EVERY STEP IS A SPECIFIC ACTION

"Add validation" is not a step. "Write test for empty email, run it, implement check, run it, commit" - that's 5 steps.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Not a step:

• "Add authentication" (too vague)
• "Implement the feature" (multiple actions)
• "Test it" (which tests? how?)

Treat plan phases as a directed acyclic graph — each phase may only depend on predecessors, never on future phases. The plan-review-gate enforces this ordering.

Decomposition trigger: If a step touches 3+ files or takes more than one sentence to describe, split it. If a phase has >5 tasks, consider splitting the phase. Individual steps target 2-5 minutes; task clusters (a full RED-GREEN-REFACTOR cycle) up to 15 minutes.

Per-phase right-sizing heuristic: A phase boundary is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. This aligns phase boundaries with cc10x's fresh-reviewer-per-phase chain — every phase is a clean handoff to a reviewer with no prior context.

• Split only where a reviewer could reject one phase while approving its neighbor. If two candidate phases would always pass or fail together, they are one phase — splitting them just doubles the gate cost for no decision value.
• Each phase must be independently demoable/verifiable — it ends on a state you can show working (a passing test, a curl, a rendered screen), not on "internals refactored, nothing observable yet."
• Don't split below the test cycle (a phase with no test of its own is a task, not a phase); don't merge above the reviewer's judgment (a phase a reviewer can't accept-or-reject as a whole is two phases).

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.
> **Design:** See `docs/plans/YYYY-MM-DD-<feature>-design.md` for full specification.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Prerequisites:** [What must exist before starting]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries. Every phase references these.]

---

If a design document exists, always reference it in the header.

Task Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts:123-145`
- Test: `tests/exact/path/to/test.ts`

**Step 1: Write the failing test**

```typescript
test('specific behavior being tested', () => {
  const result = functionName(input);
  expect(result).toBe(expected);
});

Step 2: Run test to verify it fails

Run: npm test tests/path/test.ts -- --grep "specific behavior" Expected: FAIL with "functionName is not defined"

Step 3: Write minimal implementation

function functionName(input: InputType): OutputType {
  return expected;
}

Step 4: Run test to verify it passes

Run: npm test tests/path/test.ts -- --grep "specific behavior" Expected: PASS

Step 5: Commit

git add tests/path/test.ts src/path/file.ts
git commit -m "feat: add specific feature"

## Context is King (Cole Medin Principle)

**The plan must contain ALL information for a single-pass implementation.**

A developer with zero codebase context should be able to execute the plan WITHOUT asking any questions.

### Context References Section (MUST READ!)

**Every plan MUST include a Context References section:**

```markdown
## Relevant Codebase Files

### Patterns to Follow
- `src/components/Button.tsx` (lines 15-45) - Component structure pattern
- `src/services/api.ts` (lines 23-67) - API service pattern

### Configuration Files
- `tsconfig.json` - TypeScript settings
- `.env.example` - Environment variables needed

### Related Documentation
- `docs/architecture.md#authentication` - Auth flow overview
- `README.md#running-tests` - Test commands

Why: Claude forgets context. External docs get stale. File:line references are always accurate.

Distillation Rule

Plans MUST use distilled content, not summarized. Distilled = lossless compression preserving every entity, relationship, decision, and constraint. Summarized = lossy reduction that drops specifics. If a plan section can be shortened without losing any fact the builder needs, distill it. If shortening requires dropping facts, keep the full version. Test: Could a builder agent execute from this plan alone without re-reading source files? If not, the plan is under-distilled.

Durability-Horizon Rule

Match the precision of a reference to how long the artifact sits before code touches it. File:line numbers are accurate the moment they're written and rot the moment the file changes — so use them only where the artifact is acted on immediately:

• execution_plan (acted on now, while the tree is frozen) — keep file:line Context-References. They are precise and they will still be true when the builder reads them in the next breath.
• durable-brief / decision_rfc / AFK artifacts (sit for days while code moves underneath them) — describe behavior + named types/signatures only. Reference class PaymentGateway and chargeCard(token, amountCents), never payment.ts:142. A name survives a refactor; a line number does not, and a stale line number is worse than no reference because it sends a fresh reader to the wrong place with confidence.
• Prototype-snippet exception: when a short snippet encodes a decision more precisely than prose can — an exact data shape, a tricky signature, a non-obvious call ordering — embed the snippet even in a durable artifact. The snippet captures the decision, not a volatile location, so it stays true.

Validation Levels

Match validation depth to plan complexity:

Include specific validation commands in each task step.

Production-Like Verification Planning

When the request needs real APIs, seeded data, browser flows, background jobs, or stress/load behavior, read references/live-verification-strategy.md before finalizing the plan.

Use that reference to add a ### Live Verification Strategy section that names:

• harness manifest path
• setup, reset, seed, health, and cleanup commands
• first-party system boundaries vs external dependencies
• named proof scenarios with Given/When/Then
• stress profile and pass thresholds when load behavior matters

Do not silently downgrade production-like verification into replay-only, unit-only, or manual-only steps. If the live harness does not exist yet, keep that gap explicit in the plan.

Requirements Checklist

Before writing a plan:

• Problem statement clear
• Users identified
• Functional requirements listed
• Non-functional requirements listed (performance, security, scale)
• Constraints documented
• Success criteria defined
• Existing code patterns understood
• Context References section prepared with file:line references

Prefactor Question (Advisory)

Before sequencing the build, ask one question: is there a cheap refactor that would make the upcoming change trivial? Make the change easy, then make the easy change.

Scan the target surface for small, mechanical, behavior-preserving moves that flatten the real work — extracting a function the new code will hang off, renaming a misleading symbol, pulling a constant out, splitting a parameter list. If you find one, sequence it as its own Phase 0/1 with its own test cycle, ahead of the feature phases.

This is advisory and gated — it must not fight scope discipline:

• A prefactor is in scope only when it makes the requested change demonstrably easier. "While we're here" cleanups are out of scope — defer them to a MEMORY_NOTES deferred item.
• Respect the Decision-Checkpoint: do not expand the agreed scope to chase a refactor. If the prefactor is large enough to need its own checkpoint, surface it to the user, don't smuggle it in.
• Respect the builder's >3-files guard: a prefactor phase that touches 3+ files is itself a planned, reviewer-gated phase — not a license for the builder to widen a feature task mid-flight.

Plan Completeness Gate

Before saving, verify every phase passes:

A plan missing any row is incomplete. Revise before saving.

Exit criteria by example: Do not write "Phase 1 complete when auth works." Write "Phase 1 complete when curl -X POST /api/auth/login -d '{"email":"test@test.com","password":"pass"}' returns 200 with {token: string}`." Concrete input/output examples prevent misinterpretation.

Risk Assessment Table

Classify each risk into one of four dimensions before scoring:

For each identified risk:

Score = Probability × Impact. Address risks with score > 8 first.

Risk-Based Testing Matrix

Match testing depth to task risk:

How to assess risk:

• How many files touched? (1 = low, 3+ = medium, cross-service = high)
• Is it auth/payments/security? (always high or critical)
• Is it user-facing? (medium minimum)
• Can it cause data loss? (high or critical)

Use this matrix when planning test steps. Don't over-test trivial changes. Don't under-test critical ones.

Test-Seam Selection Discipline

A seam is where the test attaches to the code. Choose seams deliberately — the plan must name them, not leave them to the builder's improvisation:

• Prefer EXISTING seams. Reuse a boundary the code already exposes (a public function, a route handler, an interface) before inventing a new one. A new seam is new surface to maintain.
• Use the HIGHEST seam possible. Test at the outermost stable boundary that still exercises the behavior — the public API, not the private helper three layers down. The highest single seam keeps the test contract stable across the builder → reviewer → verifier handoffs: the test file IS the contract, and a high seam couples it to behavior instead of to implementation detail that churns between phases.
• Minimize total seam count. Fewer seams = fewer brittle attachment points. The ideal is one seam per behavior under test. Every extra seam is another place a refactor can break a passing test.
• The two-adapters rule. A seam is only real when two concrete adapters use it — and the test double counts as the second. If only production code ever touches the seam, it is not a seam, it is a guess; do not plan a mock against it.
• Confirm chosen seams with the user. Name the seams in the plan and get agreement before the builder writes tests. A seam disagreement caught in planning is cheap; caught in review it costs a rewrite.

Functionality Flow Mapping

Before planning, document all flows:

User Flow:

1. User clicks [button]
2. System shows [form]
3. User enters [data]
4. System validates [input]
5. System saves [data]
6. System shows [confirmation]

Admin Flow:

1. Admin opens [dashboard]
2. Admin selects [item]
3. System shows [details]
4. Admin changes [setting]
5. System applies [change]

System Flow:

1. Request arrives at [endpoint]
2. Middleware validates [auth]
3. Controller calls [service]
4. Service queries [database]
5. Response returns [data]

Architecture Decision Records (ADR)

When comparing approaches, document the decision formally:

Use this format when a plan involves choosing between multiple valid approaches:

## ADR: [Decision Title]

**Context:** What situation or requirement prompted this decision?

**Decision:** What approach did we choose?

**Consequences:**
- **Positive:** [benefits of this choice]
- **Negative:** [tradeoffs we accept]
- **Alternatives Considered:** [what we didn't choose and why]

When to use ADR:

• Choosing between architectures (monolith vs microservices)
• Selecting libraries/frameworks (React vs Vue)
• Database decisions (SQL vs NoSQL)
• Authentication approaches (JWT vs sessions)

Save ADRs to: docs/decisions/ADR-NNN-title.md

Red Flags - STOP and Revise

If you find yourself:

• Writing "add feature" without exact file paths
• Skipping the test step
• Combining multiple actions into one step
• Using "etc." or "similar" instead of explicit steps
• Planning without understanding existing code patterns
• Creating steps that take more than 5 minutes
• Not including expected output for test commands

STOP. Revise the plan with more specific steps.

Rationalization Prevention

Output Format

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED: Follow this plan task-by-task using TDD.

**Goal:** [One sentence]

**Architecture:** [2-3 sentences]

**Tech Stack:** [Technologies]

**Prerequisites:** [Requirements]

**Durable Decisions:** [Foundational choices that apply across all phases — route structures, DB schema shape, key data models, auth approach, third-party service boundaries]

---

<!-- Phase 1 must be a tracer bullet — a thin vertical slice through ALL integration layers (schema → API → UI → tests). Proves architecture works before subsequent phases widen the slice. For infrastructure-only plans, Phase 1 may be setup. -->

## Phase 1: [Demonstrable Milestone]

> **Exit Criteria:** [What must be true when this phase is complete - e.g., "User can log in and receive JWT"]

### Task 1: [First Component]

**Files:**
- Create: `src/path/file.ts`
- Test: `tests/path/file.test.ts`

**Step 1:** Write failing test
[code block with test]

**Step 2:** Run test, verify fails
Run: `[command]`
Expected: FAIL

**Step 3:** Implement
[code block with implementation]

**Step 4:** Run test, verify passes
Run: `[command]`
Expected: PASS

**Step 5:** Commit
```bash
git add [files]
git commit -m "feat: [description]"

Task 2: [Second Component]

...

Risks

Success Criteria

• All tests pass
• Feature works as specified
• No regressions
• Code reviewed

## Save the Plan (MANDATORY)

**One direct save is required - the plan file. Memory indexing is router-owned.**

### Step 1: Save Plan File (Use Write tool - NO PERMISSION NEEDED)

First create directory

Bash(command="mkdir -p docs/plans")

Then save plan using Write tool (permission-free)

Write(file_path="docs/plans/YYYY-MM-DD--plan.md", content="[full plan content from output format above]")

Do NOT auto-commit — let the user decide when to commit

### Step 2: Emit Router-Owned Memory Intent (CRITICAL)

Do **NOT** edit `.cc10x/*.md` from this skill.

Instead, use the planner agent's existing `MEMORY_NOTES` contract only for durable learnings, deferred items, or verification context that is not already derivable from the planner contract.

**WHY BOTH:** The plan file is the artifact. Router-owned memory finalization derives plan indexing from `PLAN_FILE` and workflow state, so this skill must not invent a second memory serialization path.

## Router-Owned Task Tracking

The planner does **not** create execution tasks. Its job is to create the plan artifact and emit a router contract.

After planning:
- Save the plan file.
- Update memory with the plan reference.
- Let the router create workflow and execution tasks from the approved plan.

Do not instruct the planner to call `TaskCreate` or `TaskUpdate` for phase tracking.

## Plan-Task Linkage (Context Preservation)

**The relationship between Plan Files and Tasks:**

┌─────────────────────────────────────────────────────────────────────┐ │ PLAN FILE (Persistent - Source of Truth) │ │ Location: docs/plans/YYYY-MM-DD-{feature}-plan.md │ │ Contains: Full implementation details, TDD steps, file paths │ │ Survives: Session close, context compaction, conversation reset │ └─────────────────────────────────────────────────────────────────────┘ ↕ task description includes the plan file path ┌─────────────────────────────────────────────────────────────────────┐ │ TASKS (Execution Engine) │ │ Contains: Status, dependencies, progress tracking │ │ Survives: Context compaction; can be shared across sessions via │ │ task list configuration (official Claude Code) │ └─────────────────────────────────────────────────────────────────────┘

**Plan path-in-description is CRITICAL:** If context compacts mid-execution, the task description contains enough info to:
1. Find the plan file
2. Locate the exact phase/task
3. Continue without asking questions

**Phase Exit Criteria are CRITICAL:** Each phase MUST have a demonstrable milestone (not arbitrary naming):
- ❌ "Phase 1: Foundation" - Vague, when is it done?
- ✅ "Phase 1: User can authenticate" - Demonstrable, testable

## Execution Handoff

After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**

**1. Subagent-Driven (this session)** - Fresh subagent per task, review between tasks, fast iteration

**2. Manual Execution** - Follow plan step by step, verify each step

**Which approach?"**