| name | planning |
| description | Use after a design is approved and before implementing anything architectural — turning an agreed direction into an ordered, testable set of tasks. "write a plan", "break this down", "what are the steps", "plan the implementation" |
Planning
Overview
Core principle: Write the plan for someone with zero context, questionable taste, and no
instinct to test — because that someone is a fresh subagent, or 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. This is what lets a
fan-out of implementers (dispatching-subagents) each claim ready work without colliding. 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 the execution mode: fan out fresh implementers per ready task (dispatching-subagents,
default for independent tasks) or work them inline.
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.
