---
name: planning-before-code
description: Turns an approved goal into an executable implementation plan of small tasks with exact file paths, then executes with checkpoints. Use when starting non-trivial work, when the user says plan, break down, roadmap, or estimate, or before touching more than 2-3 files.
license: MIT
metadata:
  author: lammanhhoang
  version: "1.0.0"
---

# Planning Before Code

## When to use

Use when:
- The task will touch more than 2-3 files.
- The user says "plan", "break down", "roadmap", "estimate", or "how would you approach".
- You cannot list, right now and from memory, every file the change will touch. That inability IS the trigger.

Do NOT use when:
- Single-file, single-concern edit (typo, rename, one-line fix). Just do it.
- The user handed you an already-approved written plan. Skip to step 5 (Execute).
- Pure investigation or Q&A with no edits.

## Iron Law

**NO CODE BEFORE AN APPROVED WRITTEN PLAN for any task touching more than 2-3 files.**

Not a sketch in your head. Not "I'll formalize as I go." A written plan, shown to the user, explicitly approved. Zero edits before that. If you catch yourself mid-edit without one: stop, write the plan for all remaining work, get approval, then continue.

## Workflow

1. **Confirm the goal is settled.** A plan encodes decisions; it does not make them. If the approach is still open (which library, build vs. buy, API shape), resolve that with the user first.
2. **Investigate.** Read every file you expect to touch. Grep for call sites of anything you will change. The plan must name exact paths — investigation is how you earn the right to write them.
3. **Write the plan** using assets/plan-template.md. Save it to `docs/plans/<yyyy-mm-dd>-<slug>.md` (or the project's existing convention). Quality bar below.
4. **Get approval.** Present the plan. Wait for an explicit yes. Silence, "sounds interesting", or a follow-up question is not approval.
5. **Execute with checkpoints.** Batches of 3-5 tasks; protocol below.
6. **Close out.** Run the goal-state verification from the plan header. Report every deviation logged during execution.

## Plan quality bar

Every numbered task MUST have (cite by number when rejecting a plan):

1. **2-5 minutes of work.** If you would budget more than 10, split it.
2. **Exact file paths.** `src/auth/middleware.ts`, never "the auth files", "relevant tests", or "etc."
3. **A concrete change description** — which function or block, what edit.
4. **A verification step** with an exact command and expected result.

Before/after:

```markdown
### BAD — unplannable, unverifiable
3. Update the API handlers to use the new validator

### GOOD
3. Swap validateBody for zodValidate in user routes
   - Files: src/routes/users.ts (3 call sites of `validateBody(`)
   - Change: replace each `validateBody(schema)` with `zodValidate(UserSchema)`
   - Verify: `npm test -- users.routes` -> 14 passing
```

A plan whose tasks all pass the bar is executable by someone with no context. That is the test: could a fresh agent run it?

## Checkpoint execution

- Execute tasks strictly in plan order unless the plan marks them independent.
- At each checkpoint (default: every 3-5 tasks, or where the plan places one):
  1. Run every verification command from the batch — not "it looked fine".
  2. Diff reality against the plan: any file touched that the plan did not list? Any assumption in the plan header now false?
  3. Plan still valid -> continue to the next batch. Invalid -> stop and propose an amendment. Never silently continue on a drifted plan.
- **Terminal-state chaining — each phase has exactly one exit.** After planning, the only next step is executing the plan — not re-planning, not polishing the plan, not exploring one more thing. After a passing checkpoint, the only next step is the next batch. After the last batch, the only next step is close-out.
- **Amendments:** new work gets new task numbers; removed tasks stay in the plan marked SKIPPED with a reason. Never rewrite plan history — the log must show what changed and why.

## Parallel execution with subagents

Dispatch a wave of parallel subagents only when ALL hold:
- No two tasks in the wave write the same file (read overlap is fine).
- No task consumes another wave-member's output or decisions.
- Each task's text plus the plan header is self-contained — the subagent never sees this conversation.
- Each task's verification command passes without any sibling task's work in place.

Review every subagent result in two stages, in order:

1. **Spec compliance.** Only listed files modified; the change matches the task's description, not a "better" alternative; verification actually ran with matching output. Reject scope additions even when they are good — file them as proposed amendments.
2. **Code quality.** Only after stage 1 passes: correctness, consistency with surrounding code, suite still green after merging the wave.

Never accept subagent work on a green test run alone — stage 1 exists to catch "did the wrong thing well."

For the dispatch prompt template and full two-stage checklist, read references/subagent-execution.md (load only when actually parallelizing).

## Rationalization table

| Excuse | Counter |
|---|---|
| "It's just a quick change" | Count the files. More than 2-3 = plan. "Quick" changes across 4 files are how regressions ship. |
| "I'll plan as I go" | That is improvising with write access. A plan you cannot show before edit #1 is not a plan. |
| "The plan is obvious" | Obvious plans take 5 minutes to write. If it takes longer, it was not obvious — and you found out for free. |
| "The user wants speed" | Approving a 10-task plan costs 30 seconds. Reverting a wrong 4-file change costs an hour. |
| "It's all in my head" | Head-plans cannot be reviewed, resumed after context loss, or handed to a subagent. |
| "I'll document it afterwards" | That is a changelog. It reviews nothing and prevents nothing. |
| "Planning kills momentum" | Momentum toward the wrong target is the most expensive thing you can produce. |

Reaching for any of these? Stop. That's rationalization, not judgment.

## Red flags — stop immediately if

- You are editing a file that is not listed in the plan.
- Scope grew mid-execution ("while I'm here...") without a written amendment.
- You skipped approval because the user "seemed busy" or "would obviously say yes."
- The current task has run past ~10 minutes — it was under-decomposed; stop and split it.
- You cannot state the current task's verification command without looking.
- You are on task 8 and the checkpoint after task 5 never ran.
- The plan contains "etc.", "as needed", "relevant files", or any path-free task.
- You are re-planning after approval with no new information. That is stalling — execute.

## What NOT to do

- Do not write the plan and start coding in the same turn. Approval is a separate turn unless the user pre-authorized auto-execution.
- Do not write phase headers that hide unknown work ("Phase 1: Setup"). Every task is a concrete edit with a path.
- Do not defer all verification to the end. A batch of 5 unverified tasks means bug #1 hides under 4 layers of later work.
- Do not let a failing verification slide with "will fix later" unless a numbered later task already covers it.
- Do not parallelize dependent tasks to save time. Merge conflicts plus rework cost more than sequencing.

## Output template

assets/plan-template.md — copy it verbatim for every plan; keep the Execution log table updated as you work. It is the resume point after any interruption or context loss.