Planning

Overview

Core principle: Write the plan for an implementer with zero context, questionable taste, and no instinct to test — whether that is a fresh subagent, you after compaction, or you at 2am. Everything the implementer needs is in the plan; nothing lives only in your head or the chat.

A good plan turns a design into a sequence of tasks that each end in something you can run and check. It is the bridge between shaping (what & why) and the build (how).

Map the Structure First

Before tasks, lay out the pieces: what files/modules exist, each with one responsibility. A clear structure makes the tasks fall out naturally. If you can't name a piece cleanly, the design isn't settled — go back to shaping (and see naming-as-design).

Right-Size the Tasks

• A task is the smallest chunk worth a reviewer's gate — it ends in an independently testable, runnable deliverable. Not "build the parser" (too big); not "add a semicolon" (too small).
• Inside a task, steps are bite-sized (a couple of minutes each), test-first where it's keeper code.
• Each task names its interfaces: what it consumes and what it produces, with the actual signatures — not "a function that parses input" but the real name, args, and return shape.

No Placeholders

IF THE PLAN SAYS "TBD" OR "SIMILAR TO ABOVE", IT ISN'T A PLAN YET

Ban "add error handling", "etc.", "TBD", "like task 2". Write the real thing. A placeholder is a decision you're pushing onto someone with less context than you have right now. Repeat real code rather than referencing it vaguely.

File It As Beads

The plan is not a document that rots in a folder — it's beads (using-beads):

bd create "Parser: tokenize input" -t task -p 1
bd create "Parser: build AST"      -t task -p 1 --deps blocked-by:<tokenize-id>

Record dependencies so bd ready surfaces exactly what's buildable next. The same graph supports one inline implementer or, when the host permits and tasks are independent, a fan-out of implementers (dispatching-subagents) without collisions. For a larger effort, also keep a short plan note in the repo; for most work, the beads are the plan.

Self-Review Before Handing Off

Check the plan against the approved design:

• Coverage — every part of the design maps to a task; nothing designed is unplanned.
• No placeholders — every task is concrete enough to implement blind.
• Interfaces line up — what one task produces is what the next consumes, names and shapes matching.

Then pick an execution mode the host permits. Fan out fresh implementers only when independent work and saved wall-clock justify it (dispatching-subagents); otherwise work the dependency order inline. The plan must be equally actionable in either mode.

Common Mistakes

• Tasks too big to review. If a task can't be checked in one sitting, split it.
• Vague interfaces. "Passes the data along" hides the exact mismatch that will bite in integration. Write signatures.
• Planning what won't be built. YAGNI applies here too — don't plan the speculative feature shaping already cut.
• A plan nobody can act on without you. If the implementer would have to ask you a question, answer it in the plan first.