Context
Multi-file work where the wrong design decision is expensive to undo: a schema change, a module boundary, a rename that crosses layers. The failure you are trying to avoid is not a typo - it is a complete, competent implementation of the wrong approach.
Problem
Reviewing a diff is the worst possible moment to catch a design error. By then the agent has committed to a shape, the change is large enough that the reviewer skims, and rejection wastes the entire run. Yet the diff is usually the only artefact anyone looks at.
Pattern
Before implementation, the agent writes a plan to a versioned file - PLAN.md, a task file, an ADR
stub - containing: the files it will touch, the approach in ordered steps, the assumptions it is
making, and what it will not do. The run pauses there. A human approves, edits, or rejects the
plan, and only then does implementation start.
Two details make it work in practice:
- The plan is an artefact, not a chat message. It survives the session, it is diffable, and it can be attached to the pull request. A plan that only exists inside the transcript is a plan nobody re-reads.
- Assumptions are a required section. Most bad plans are not wrong about the steps; they are wrong about a fact the agent assumed. Making assumptions explicit is the highest-value line in the file.
Tradeoffs
It adds a round trip, and it is genuinely annoying on small tasks. It also produces false confidence: an approved plan can make a reviewer feel the work is vetted when only the shape was vetting, not the implementation.
When not to use it
Single-file edits, mechanical changes with an obvious diff, and anything where the plan would be longer than the change. The test: if the plan cannot be shorter than the diff will be, the task was small enough that the gate is pure overhead.