writing-plans

name	writing-plans
description	Use when creating implementation plans. Break specs into bite-sized tasks (2-5 min each).

Writing Plans

When to Use

∀ plan workflow, after spec approved.

HARD-GATE

∀ task ∈ plan: must have exact file path, complete code snippet, exact command to run, expected output. "Assumes engineer has zero context ∧ questionable taste."

Task Granularity

Each task = 1 action (2-5 minutes):

• "Write failing test for X" = 1 task
• "Run test, observe FAIL" = 1 task
• "Implement minimal code to pass" = 1 task
• "Run test, observe PASS" = 1 task
• "Commit with message Y" = 1 task

¬combine multiple actions into one task. ¬"implement feature X" (too broad).

Plan Structure

## Wave 0 (parallel)

### T01: Write failing test for [feature]
- **File**: `src/domain/feature.spec.ts`
- **Code**: [exact test code]
- **Run**: `npx vitest run src/domain/feature.spec.ts`
- **Expect**: FAIL — "feature is not defined"
- **AC**: AC1

### T02: Implement [feature]
- **File**: `src/domain/feature.ts`
- **Code**: [exact implementation]
- **Run**: `npx vitest run src/domain/feature.spec.ts`
- **Expect**: PASS — 1/1 tests passing
- **Commit**: `feat(auth/T02): add feature`

## Wave 1 (depends on Wave 0)
...

Wave Assignment Rules

• Tasks with ¬ dependencies -> Wave 0
• Tasks depending on Wave N -> Wave N+1
• Tasks within same wave -> parallelizable
• Detect via topological sort

Review Loop

1. Write plan -> save PLAN.md
2. Anonymous plan reviewer (fresh subagent, max 3 iterations)
3. Plannotator review (user annotates)
4. Approved -> proceed to execute

Anti-Patterns

• Tasks without exact file paths ("update the relevant files")
• Tasks without expected output ("tests should pass")
• Combining test-writing ∧ implementation ∈ same task
• Plans that skip TDD steps (standard/complex tasks require them)
• Wave assignments that don't match dependency graph

Rules

• ∀ task: 1 file, 1 action, 1 commit
• ∀ standard/complex task: TDD steps (write test -> fail -> implement -> pass -> commit)
• Simple tasks: simpler (may combine steps, skip TDD)
• ¬proceed to execute until plan approved