writing-plans

Writing Plans

Write the plan for a skilled developer who knows nothing about this codebase, this toolset, or this domain, and whose taste you do not trust. Every task names exact files, contains complete code, and ends with a verified test cycle. DRY, YAGNI, TDD, frequent commits.

Before drafting

1. Scope check. A spec spanning multiple independent subsystems becomes multiple plans, one per subsystem, each producing working software on its own. Suggest the split before writing one bloated plan.
2. File structure first. Map which files get created or modified and each file's single responsibility. Decomposition gets locked here: clear boundaries, focused files, split by responsibility rather than technical layer. In existing codebases follow the established patterns; do not unilaterally restructure.
3. Save location. docs/plans/YYYY-MM-DD-<feature-name>.md. User preference overrides.

Task right-sizing

A task is the smallest unit that carries its own test cycle and deserves a fresh reviewer's gate. Fold setup, config, and docs into the task whose deliverable needs them. Split only where a reviewer could reject one task while approving its neighbor. Every task ends with an independently testable deliverable.

Within a task, each step is one 2-5 minute action: write the failing test, run it and watch it fail, implement minimally, run it and watch it pass, commit.

Required plan skeleton

Every plan opens with a header: goal in one sentence, architecture in 2-3 sentences, tech stack, and a Global Constraints section with the spec's project-wide requirements (version floors, naming rules, platform requirements) copied verbatim, one line each. Every task implicitly includes that section.

Every task carries a Files block (exact create/modify/test paths, with line ranges for modifications) and an Interfaces block: what it consumes from earlier tasks and what later tasks rely on, as exact signatures. A task's implementer sees only their own task; the Interfaces block is how neighboring names and types stay consistent.

Read references/plan-template.md for the full header and task skeleton with a worked TDD step sequence.

No placeholders

These are plan failures. Never write them:

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" or "handle edge cases"
• "Write tests for the above" without the actual test code
• "Similar to Task N" instead of repeating the code (tasks get read out of order)
• Steps that describe without showing: code steps require code blocks
• References to types or functions not defined in any task

Self-review

After writing the full plan, check it against the spec with fresh eyes. Three passes:

1. Coverage: every spec requirement points to a task. List gaps, add tasks.
2. Placeholder scan: search for the patterns above. Fix inline.
3. Type consistency: signatures and names used in later tasks match their definitions in earlier tasks. clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

Fix and move on. No re-review loop.

Execution handoff

After saving, offer the choice: subagent-driven-development (fresh subagent per task, reviews between, recommended) or executing-plans (batch execution in session with checkpoints). Isolation comes from using-git-worktrees at execution time, not from the plan.

Good vs bad

Bad task step: "Step 3: Implement the validation logic with appropriate error handling, similar to Task 2." Three placeholder patterns in one sentence; the implementer must guess the code, the errors, and Task 2's contents.

Good task step: "Step 3: Write minimal implementation" followed by the actual 12-line function in a code block, then "Step 4: Run pytest tests/test_validate.py::test_rejects_empty -v. Expected: PASS."

Verification

After self-review, grep the saved plan: grep -nE "TBD|TODO|implement later|appropriate error|Similar to Task|handle edge cases" docs/plans/<file>.md. Expect zero matches. Then confirm every task has Files, Interfaces, at least one failing-test step with expected output, and a commit step. Any miss: the plan is not ready to hand off, fix it first.

Completion checklist

• [ ] Scope check done; multi-subsystem specs split
• [ ] Header present with Global Constraints copied verbatim
• [ ] Every task: exact paths, Interfaces block, full TDD step cycle, commit
• [ ] Complete code in every code step, exact commands with expected output
• [ ] Placeholder grep returns zero matches
• [ ] Coverage and type-consistency passes done
• [ ] Plan saved to docs/plans/, execution choice offered

Any box unchecked: not done. Fix or say so.

Footguns

• Planning for yourself. You hold context the executor will not have. Every "obviously" in your head is a missing sentence in the plan.
• Tasks split by layer. "Task 1: all models, Task 2: all handlers" means nothing works until everything works. Split vertically so each task ships a testable behavior.
• Cross-task name drift. The most common execution-breaking bug in plans. The Interfaces blocks plus the type-consistency pass exist to kill it; skip neither.

Red flags

Catching yourself writing any of these means the plan is not done:

• "Details to be worked out during implementation"
• "The engineer can figure out the test"
• "Same as above"
• "Add error handling as needed"

A plan with holes delegates its thinking to the executor, which is the exact thing a plan exists to prevent. Complete code and exact commands, or keep writing.