Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 8 of 30

Planning

0 of 30 complete

Why it matters

An agent given a vague request will start editing and discover the shape of the problem halfway through the diff. By then the context is spent and the change is hard to unwind. Writing a plan after discovery forces the agent to name the files, the order and the check that ends each step, which gives a human a cheap place to catch a wrong assumption before any code exists.

Mental model

It is a building permit listing scope, inspections and sign-off. The metaphor breaks because the survey that justifies the permit happens first, and it often changes the scope the permit was written for, so the plan is a draft until the first read is done.

How it works

One outcome, four checked stepsInteractive
16 nodes · 6 branches
stagevalidation gaterootquestionnoteruled out or rejected

Step 1 of 7

Name the end

The plan opens with a test that fails today and must pass. Every later step is judged against that line, which is why 'fix the totals bug' does not qualify.

root · current

Outcome · checkout.spec.ts passes

The plan starts from a check anyone can run. 'Fix totals' is not an outcome; a named test that currently fails is.

Root of the hierarchy

Step 1/7 · Name the end

Figure. A plan written from a discovery read: one observable outcome at the root, four steps in dependency order, and the check or gate that ends each step. The rejected branch is the same request restated as steps, which names no file and no check; the marked unknown is the one assumption the plan cannot resolve alone.

What to notice. The test, the files and the legacy path are an authored example; the page gives no measured plan sizes, so no counts are drawn. The siblings are in plan order, but the tree's claim is ownership, not chronology: each step is independently verifiable and every check hangs off the step it ends. Omitted: the discovery reads' contents and the diff itself, which the page treats as execution rather than planning.

Text version

A plan drawn as a hierarchy. The root is one observable outcome: checkout.spec.ts passes for annual plans. A rejected branch, the re-stated request, has four steps — investigate, fix the bug, add tests, run tests — each naming no file and no check, and is drawn crossed. The accepted plan has four steps in order. Step 1 reads totals.ts, tax.ts and plan.ts, checked by reproducing the failing test for the intended reason. Step 2 changes rounding in tax.ts lines 41 to 58, checked by the EU and annual case passing. Step 3 adds the annual case to checkout.spec.ts, checked by the new case failing on the base commit and passing here. Step 4 deletes the legacy rounding path and waits on an approval gate, because no test can prove the removal safe. A marked unknown asks whether plan.period reaches tax.ts and names the read that resolves it. A revision note records why the plan changed after a failing check.

  1. Restate the task as an observable outcome, such as which test passes or which command exits zero.
  2. Do discovery first and write the plan from what was found, naming specific files and functions.
  3. Order steps so each is independently verifiable and leaves the tree buildable.
  4. Mark the steps you are unsure about and the check that would resolve each one.
  5. Get approval for any step that deletes data, changes a dependency or touches infrastructure.
  6. Revise the plan when a check fails and record why it changed.

Trade-offs

ChoiceGood forCostFails when
Plan then executeCatches scope errors earlyAn extra turn before any codeTask is a one-line fix
Per-step approvalControl over risky editsInterrupts flow, slows long tasksWork is repetitive and low risk
Living checklist the agent updatesProgress visibilityBookkeeping tokens, stale itemsSteps are exploratory
Act directly, no planFast for tiny changesDrift and duplicated workTask spans multiple files
Trade-off mapInteractive

Good for

Catches scope errors early

Cost

An extra turn before any code

Fails when

Task is a one-line fix

  1. Task is a one-line fix
  2. Work is repetitive and low risk
  3. Steps are exploratory
  4. Task spans multiple files

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Plan then execute is good for Catches scope errors early, costs An extra turn before any code, and fails when Task is a one-line fix. Per-step approval is good for Control over risky edits, costs Interrupts flow, slows long tasks, and fails when Work is repetitive and low risk. Living checklist the agent updates is good for Progress visibility, costs Bookkeeping tokens, stale items, and fails when Steps are exploratory. Act directly, no plan is good for Fast for tiny changes, costs Drift and duplicated work, and fails when Task spans multiple files

Failure modes

  • Plan restates the request. Steps say investigate and fix without naming a file, so nothing is checkable. Debug: verify every step names a file, command or test.
  • Plan frozen after contradiction. A failing test disproves step two and the agent continues anyway. Debug: compare plan revision times with the last failing check.
  • Plan grows past the task. The agent refactors adjacent code because the plan expanded. Debug: diff the changed file list against the files the plan named.

In production

Store plans with the run trace and measure overlap between planned and changed files. Cap plan length, since a plan longer than the eventual diff usually signals scope creep.

Common misconceptions

People think: Planning is only for large tasks.

Actually: A two-line plan on a small task still exposes a wrong assumption before the first edit.

People think: A plan guarantees the agent follows it.

Actually: Plans drift; the value is the checkpoint, not compliance.

Interview angle

Explain when planning earns its extra turn and when it does not. The strong version puts the plan after discovery, names files and per-step checks, and treats it as revisable when a test contradicts it. Reciting a numbered restatement of the request, with no checkpoint and no approval rule, is the weak answer.

Sources