writing-solid-planslisted

# Writing Solid Plans Write the plan for an engineer (or a fresh agent) with zero context for this codebase. Everything they need must be in the plan itself. ## Before designing - Confirm purpose, constraints, and success criteria. Ask only the questions whose answers would change the design. - If the request bundles several independent subsystems, decompose into sub-projects first — one spec/plan each. - Propose 2-3 approaches with trade-offs and a recommendation before committing to one. YAGNI: cut anything the goal doesn't need. ## Plan content - Exact file paths for every create / modify / test. - Real code in code steps; exact commands with expected output. - Each task leaves the codebase working and testable; commit per task. **Forbidden placeholders — each one is a plan failure:** - "TBD", "TODO", "fill in later" - "Add appropriate error handling / validation / edge cases" - "Write tests for the above" (without the actual test code) - "Similar to Task N" (repeat the content — tasks may be read out of order) - References to functions or types that no task defines ## If the plan outlives this session A plan executed across sessions, reviewed by others, or run alongside other in-flight changes must live on disk — [[durable-plans]] holds the file convention and lifecycle (persist, sync, retire). ## Self-review before handoff 1. **Coverage:** every spec requirement maps to a task — list any gaps. 2. **Placeholders:** scan for the forbidden patterns above. 3. **Co