writing-plans

Writing Plans

Write enough of a plan to execute the complete request without rediscovering scope or inventing interfaces. Planning is part of authorized implementation, not a separate approval transaction. Plan-only requests remain plan-only.

The plan is the set of decisions an implementer cannot make alone: what done means, which files and symbols, which interfaces cross task boundaries, which checks prove each outcome. Everything a competent implementer derives from the codebase stays out. If implementation bodies dominate, replace them with signatures and checks. Lines that decide nothing ("handle edge cases", "add appropriate validation") are the opposite failure.

Scope and structure

• Start from the actual requirements or existing spec; identify what done means.
• Inspect project conventions and affected paths before naming changes.
• Split by independently testable outcomes, not file counts, elapsed time or individual tool calls. Fold setup, configuration, scaffolding and documentation into the task whose deliverable needs them; split only where a whole outcome is separately rejectable. Include failure paths in the task whose deliverable needs them.
• State dependencies and exact shared interfaces before parallel execution. Keep related changes together; no unrelated refactoring.
• Define behavior checks before implementation. Bug fixes need a failing reproduction; do not prescribe tests that assert source text or wiring.

Plan content

A useful plan contains:

1. Goal and boundaries: full requested outcome, exclusions, constraints.
2. Approach: existing patterns reused, important decisions and risks.
3. Global constraints: project-wide requirements from the spec or user — version floors, dependency limits, naming or copy rules, platform requirements — one line each with exact values, verbatim. Every task implicitly includes this section; do not restate it per task.
4. Changes: exact files/symbols and required behavioral changes, ordered by dependency. Include caller migration and obsolete-path removal when needed.
5. Per-task contracts: for each task, inputs/outputs/failure behavior and the interfaces it consumes from earlier tasks and produces for later ones — exact names, signatures and value shapes. A worker who sees only their own task learns neighboring names from these blocks, not from the other tasks' bodies.
6. Review focus: boundary and failure inputs the spec implies but no task's checks exercise — empty/oversized/malformed input, the "impossible" state a caller can still build, platform or locale edge — one line each, most likely to bite a real user first. Each line names the input, the behavior a reasonable person would expect, and the task that owns the code; the check is added to that owning task. An empty section means you checked and found none, not that you skipped the check.
7. Verification: scenario/command, observable expected result and isolation.