Jesse Vincent (obra) / writing-plans
Why write a plan when the agent could just start?
Because the plan is the only part of the work that survives a lost context.
What to remember
- A plan is the recovery mechanism when context is lost, which happens constantly on long work.
- Steps without a definition of done are wishes, not steps.
- Reviewing a plan is far cheaper than reviewing a finished implementation.
- It is the natural bridge between brainstorming and subagent driven development.
01What it changes in practice
Long agent tasks fail in a specific way: the conversation grows, earlier decisions fall out of context, and the agent starts contradicting work it did an hour ago. A plan on disk is immune to that, because it is re-read rather than remembered.
It also makes disagreement cheap. Arguing about a plan takes minutes, while arguing about a finished implementation costs whatever it took to build.
02Where it disappoints
Plans go stale. A plan that no longer matches the code is worse than none, because it is trusted, so update it when reality diverges.
Over planning is real too. Small work does not need a document, and producing one is procedure for its own sake.
Install and first run
- Install superpowers from obra/superpowers, published under MIT.
- Insist that each step names a file or a component and a way to tell that it is done.
- Keep the plan in the repository, so it is reviewable and survives the session.
Questions people actually ask
- Where should the plan live?
- In the repository, so it can be reviewed, versioned and re-read by another session or another agent.
- What makes a step good?
- A named target and a way to tell it is finished. Without that, progress cannot be checked.
- When is planning too much?
- When the task fits in one sitting and one sentence. Then the plan is ceremony.
Sources
Machine readable versions of this page