writing-plans

Start with a plan header containing goal, architecture, tech stack, and global constraints copied verbatim from the spec. Then map the file structure, decompose work into right-sized tasks, and write each task as bite-sized TDD steps with exact file paths, test code, run commands, and commit messages.

Each task should be the smallest unit carrying its own test cycle, ending with an independently testable deliverable. Fold setup and scaffolding into the task that needs them, and split only where a reviewer could reject one task while approving its neighbor.

Each step should be one action taking 2-5 minutes: write the failing test, run it to confirm failure, write minimal implementation, run tests to confirm pass, then commit. Every code step must include actual code blocks, never placeholders like TODO or 'add appropriate error handling'.

Split when the spec covers multiple independent subsystems. Each plan should produce working, testable software on its own, so one plan per subsystem keeps scope reviewable and prevents a single plan from becoming unimplementable.

Common failures include placeholder text, references to undefined types or functions, inconsistent naming across tasks, and steps that describe what to do without showing how. A self-review pass checking spec coverage, placeholders, and type consistency catches these before handoff.