Why Review an Agents Plan

Why review an agent's plan

npm install --global @thisisnsh/planx

An agent that plans before it codes is already better than one that does not. The question this page answers is the next one: why the plan is worth reading properly, and what it costs when you do not.

The plan is the last cheap place to disagree

Everything an agent does after the plan is expensive to undo. A wrong approach becomes twelve files, a test suite that passes against the wrong behaviour, and a diff too large to review honestly — at which point the realistic options are to accept it or to throw away an hour.

The same disagreement, expressed against a plan, costs one sentence.

This is not an argument about AI. It is the same reason a design doc is cheaper to change than a shipped feature. What is new is that the agent produces the plan in seconds, which makes it tempting to treat it as free — and to skim it the way you would skim something free.

Why skimming is the default

The plan arrives as one long message, at once, in a scrollback you are also using for everything else. It is well-written and confident. There is an accept button under it.

Every property of that presentation encourages approval:

• It is not addressable. You cannot point at a line. Disagreement has to be re-typed as prose — "in the third section, where it says the migration runs first, actually..." — so small objections are not worth raising and go unraised.
• It is not comparable. When the agent revises, you get another long message. Nothing tells you which fifteen words changed, so re-reading the whole thing is the only honest option and skimming is the realistic one.
• It disappears. The plan you approved is somewhere in a scrollback, and the thing being built is whatever the agent still remembers of it. There is no copy to check the result against.
• It is all-or-nothing. Approve or reject. A plan that is 95% right has no gesture that means "this, but not line 40".

The failure this produces is not the agent doing something absurd. It is the agent doing something reasonable that you would not have chosen, in a plan you approved without quite reading, and nobody noticing until the code exists.

What changes when the plan is an artifact

PlanX stores the plan as a file with a version number and puts a review over it. The four problems above stop being properties of the medium:

The problem	What replaces it
Not addressable	Line comments — v to select, f to comment. See Feedback and edits
Not comparable	A word-level diff against the previous version, unchanged runs collapsed. See Versions and diffs
Disappears	A file in ~/.planx, one directory per plan, every version kept
All-or-nothing	Comment, edit a line yourself, or approve an exact version

And one thing that has no equivalent in chat at all: because the plan is a file rather than a conversation, the agent that builds it does not have to be the agent that wrote it. See Custom agents.

Reviewing is not more planning

The point is not to make the agent write longer plans, or to add a ceremony before work can start. A plan you approve without reading is worse than no plan, because it converts your judgement into a rubber stamp and adds a step.

The point is the opposite: make the plan short enough to read, structured enough to fold, and specific enough to disagree with — then actually disagree with it. PlanX exists for the disagreeing. Everything else in it is scaffolding for that one act.

What it looks like in practice

You read the plan with space folding the sections you already agree with, so what is left on screen is the part you are actually deciding about. You put a comment on the two lines that are wrong. You rewrite one line yourself, because the right wording was obvious. You hand it back. The next version arrives as a diff of what changed, so re-reading costs seconds instead of minutes. You approve v2 by number, and v2 is what gets built.

Three minutes, and the thing that gets built is the thing you decided on.

Next

• Plan mode vs. a reviewable plan — how this relates to the plan mode you already have.
• Planning with Claude Code or Planning with Codex — the workflow in your agent.
• Reviewing — the review screen and every key on it.