How to Review an AI Agent's Plan Before It Writes Code

Jul 07, 2026·Last updated on Jul 07, 206

Share this article:

Author: Pepe

A checkpoint that pauses an agent before it writes code only helps if you know what to do with the pause. Plenty of teams have plan review turned on and still ship agent-written bugs, because the review itself is a rubber stamp: read the plan, feel like it's probably fine, approve it. This is about the part that actually matters: what separates a plan worth approving from one that's going to cause you pain three files later, and how to give feedback that improves it instead of just blocking it.

Rubber-Stamping Defeats the Point

Most AI coding tools offer some version of plan mode: the agent describes what it intends to do, you look at it, you approve. The mechanism works. The judgment behind it often doesn't.undefined

Two failure modes show up constantly. The first is skipping review under time pressure, which is a discipline problem and has a structural fix (a pipeline step the agent can't get past without your input, rather than a mode you have to remember to toggle). The second is worse, because it looks like review is happening: you read the plan, it sounds reasonable, you approve it without actually checking whether it addresses the parts of the task that matter. A plan can be well-formatted and still wrong.

The rest of this piece is a working rubric for the second problem.

What to Look For in a Plan

A plan worth approving does five things. It's rare to find all five in a first draft, which is exactly why you're reviewing it instead of skipping straight to execution.

It names specific files and changes, not categories of work. "Update the auth module" is not a plan; it's a restatement of the task. "Add a refreshToken check to middleware/auth.ts, update the three call sites in routes/api/*.ts that assume synchronous auth, and add a migration for the new token_version column" is a plan. If you can't tell which files will change before execution starts, you can't meaningfully approve or reject anything.

It explains why, not just what. A list of edits with no rationale forces you to reverse-engineer the agent's reasoning after the fact, which is slower than if it had just told you up front. Look for a sentence or two per change explaining the reasoning, especially anywhere the approach isn't obvious.

It surfaces assumptions and unknowns instead of hiding them. A plan that says "assuming the User table doesn't have other consumers of this field, I'll rename it directly" is doing its job: it's telling you where it might be wrong, so you can correct it before code exists. A plan with no stated assumptions either did no risk analysis or is hiding it.

It's sized to match the task. A plan for a one-line bug fix that touches nine files is a sign the agent misunderstood scope. A plan for a cross-cutting refactor that touches two files is a sign it didn't find all the call sites. Scope mismatches are one of the easiest things to catch in a plan and one of the most expensive to catch after implementation.

It identifies the risky part of the change. Schema changes, anything touching auth or payments, public API signatures, anything that runs in a migration. If the task touches one of these and the plan doesn't call it out specifically, that's a gap, not a non-issue.

Red Flags That Should Trigger a Rejection, Not a Note

Some plan issues are worth a quick revision request. Others mean the agent didn't understand the task well enough for you to trust the plan at all, and asking for a patch on top of it wastes a review cycle. Reject and re-plan when you see:

Vague verbs doing all the work: "refactor as needed," "clean up related code," "update accordingly." These mean the agent hasn't actually decided what to do yet.
A file list that doesn't match your own mental model of where the change should live, with no explanation for the discrepancy.
No mention of tests, when the task obviously needs them.
A plan that contradicts an existing pattern in your codebase without acknowledging it. If you have a repository pattern for data access and the plan proposes direct queries, either the agent didn't see the existing pattern or it has a reason for breaking it. A plan that's silent on this hasn't done its job.
New dependencies introduced without justification.

None of these are about the agent being "bad." They're signals that the plan was generated without enough context, and more context (a clearer prompt, a pointer to the relevant existing code) will get you a better plan faster than iterating on a weak one.

Giving Feedback That Improves the Plan

Once you've read the plan against the rubric above, you have three moves: approve, request changes, or reject outright.

Approve when the plan covers the five points above and the risk areas are ones you understand and accept. Request changes when the plan is directionally right but has a specific, nameable gap, missing a file, an unaddressed edge case, a scope that's slightly off. Be specific in the request; "this needs more detail" produces another vague plan, while "you didn't account for the case where the user has no existing session" produces a fix. Reject and ask for a fresh plan when the red flags above show up, since patching a plan built on a wrong understanding of the task usually costs more than starting over.

Unstoppable Code's plan review runs through an approval step in the pipeline: the agent's plan pauses there, and the pipeline doesn't continue until you approve, request revisions, or reject. What you do at that step is the part covered above. The tool creates the pause; the rubric is what you bring to it.

Reviewing at Scale, Across Parallel Agents

The rubric above works the same whether you're reviewing one plan or five. What changes at scale is throughput, not judgment. Each agent runs in its own isolated worktree, so five agents produce five independent plans you can review in whatever order you want, without one agent's in-progress work blocking your read of another's plan. How to Manage Parallel Agents Without Losing Track covers the coordination side of running that many agents at once; this piece is specifically about what you do when a plan lands in front of you.

Here's a minimal pipeline that puts a real approval step between planning and implementation, using the schema as it actually ships (jobs, steps, uses, and needs to sequence them):

pipeline:
  name: 'Plan-Reviewed Implementation'
  version: '3.0'
  description: 'Draft a plan, pause for human approval, implement, then run tests.'
  scope: worktree
  on:
    task_ready:
      inputs:
        model:
          type: choice
          description: Choose the planning model.
          options: [opus, gpt-5.5]
          default: opus
  jobs:
    plan:
      name: Create Plan
      steps:
        - id: create_plan
          uses: builtin/agent-prompt
          with:
            model: ${{ inputs.model }}
            permission_preset: plan
            prompt: 'Analyze the task. List every file you will touch, the changes, and why.'
    review:
      name: Human Approval
      needs: plan
      steps:
        - id: approve
          uses: builtin/request-input
          with:
            prompt: 'Review the plan above. Approve, request changes, or reject.'
    implement:
      name: Implement Plan
      needs: review
      steps:
        - id: build
          uses: builtin/agent-prompt
          with:
            model: ${{ inputs.model }}
            prompt: 'Implement exactly what was approved. Do not deviate.'
    test:
      name: Run Tests
      needs: implement
      max_retries: 2
      steps:
        - id: run_tests
          shell: bash
          run: npm test

Because implement needs review, it doesn't start until the approval step resolves, no matter how many of these are running in parallel across your worktrees.

Single-Agent Review vs. Batched Parallel Review

Plan review mechanism

Single-agent tools (Cursor, vanilla Claude Code): mode toggle or prompt discipline.

Unstoppable Code: a pipeline job with a human-approval step other jobs depend on.

What prevents skipped review

Single-agent tools: your attention.

Unstoppable Code: the job graph. A downstream job doesn't start until the jobs it needs finish.

Review throughput

Single-agent tools: linear, review one plan, then start the next task.

Unstoppable Code: batched, review several plans and approve them in any order.

What still depends on you

Both: whether the plan is actually good. No pipeline step checks a plan's file list against the task, weighs its risk areas, or catches a scope mismatch. That's the review skill this piece is about, and it's identical whether you're reviewing one plan or ten.

A Quick Reference

Before you approve a plan, check that it:

Names specific files and changes, not a restatement of the task
Explains why for anything non-obvious
States its assumptions instead of burying them
Is sized to match the actual task
Calls out the genuinely risky part of the change, if there is one

If it's missing two or more of these, that's a request-changes, not an approve. If it's vague across the board, reject it and ask again with more context rather than patching it.

Wrapping Up

The pipeline step that pauses an agent before it writes code is table stakes; most serious tools have some version of it now. What separates a team that benefits from plan review from one that has it turned on and still gets burned is whether the human on the other end of that pause knows what a good plan looks like. Use the rubric above, be specific in your feedback, and reject early when a plan shows the red flags rather than iterating on something that was never going to be right.

For the broader case on why isolation and structural gates beat relying on discipline in the first place, see How to Supervise AI Coding Agents (link once published, suggested URL: unstoppabledomains.com/blog/categories/education/article/how-to-supervise-ai-coding-agents). For what this looks like when the codebase is regulated or production-critical, see How to Use AI Agents Safely on a Production Codebase (suggested URL: unstoppabledomains.com/blog/categories/education/article/ai-agents-production-codebase). This piece is the one to come back to for the actual reviewing, not the architecture around it.

Unstoppable Code ships the pipeline mechanics behind this workflow, worktree isolation, job dependencies, and a human-approval step, out of the box. Try it at code.unstoppabledomains.com.