Review the Plan Before You Review the Diff

The most consequential review of an AI-generated change often belongs before implementation begins. That is when a team can still challenge the problem, expose missing constraints, and choose a different approach without having to unwind a large pull request.

Coding agents make it easier to produce an implementation quickly. They can also turn an ambiguous ticket into a convincing solution before anyone has agreed on what the solution should do. By the time the code reaches review, the team is trying to assess both the design and its execution at once.

A shared implementation plan creates an earlier opportunity for judgment. It gives engineers a concrete proposal to question, gives the author useful feedback, and gives an agent a clearer basis for execution. The aim is to build confidence in the decision before investing in the implementation.

Key Takeaways

• Review intent, constraints, and trade-offs before an agent begins a consequential change.
• Keep the plan in a shared, versioned location so reviewers and implementers work from the same agreement.
• Scale planning effort to the risk of the change.
• Define what an approved plan authorizes and when new discoveries require another decision.
• Review the final code and verification evidence against the plan before delivery.

Why AI code review needs an earlier feedback loop

A code review can catch implementation problems, but it is an expensive place to discover disagreement about what should have been built.

Imagine an agent adding a customer-data export. It produces an endpoint, a query, and a download button. The tests pass. During review, someone points out that large exports must run asynchronously, permissions can change while a job is queued, and the result must expire after a limited period.

Those are design constraints. Adding them may change the architecture, the data model, and the rollout. The agent worked quickly, but the team now owns a substantial amount of rework.

An earlier review would make those constraints explicit before they spread across the implementation. It would also give the people who understand the existing system a chance to contribute. That is the practical value of preserving a shared theory of the system: the team’s knowledge can shape the work before it becomes code.

Faster code generation does not guarantee faster delivery

Software delivery includes the decisions and operational work surrounding implementation. Requirements, access boundaries, testing, rollout, and support all affect whether a change creates value.

DORA’s 2025 research describes AI as an amplifier of an organization’s existing strengths and weaknesses. Its findings support a broader view of improvement: adopting a coding tool is only part of changing how a team delivers software. Read the DORA report.

For a team, the implication is straightforward. Time saved during implementation can be consumed by review delays, repeated revisions, or production failures. The useful measure is how efficiently a change moves from a justified need to a verified outcome.

Plan review is one way to improve that process. It gives the team a chance to challenge assumptions while changing direction is still relatively inexpensive.

What is a Plan Review Request?

A Plan Review Request is a proposal for a software change that the relevant people review before implementation. It states the intended outcome, the existing constraints, the proposed approach, and how the result will be verified.

The plan should live somewhere the team can find and discuss it: a repository document, a pull request containing only the plan, or a linked design document with version history. The important property is a shared record of the decision that helps prevent cognitive debt. A private conversation with an agent is a poor substitute when several people need to evaluate or execute the work.

A practical workflow has five steps:

1. Investigate. Read the relevant code, tests, requirements, and operational constraints.
2. Propose. Write a plan that identifies the approach, alternatives, risks, and open questions.
3. Review. Ask the appropriate engineers to challenge the consequential decisions.
4. Implement. Use the agreed plan as the brief for a human author or coding agent.
5. Verify. Review the result against the plan and record any material departures.

The plan can evolve. If implementation exposes a mistaken assumption, update the record and resolve the affected decision before continuing with work that depends on it.

What an AI implementation plan should contain

A useful plan makes important choices visible without attempting to predict every line of code. A reviewer should be able to understand the proposal, locate the supporting evidence, and identify what remains unresolved.

Outcome and scope

Describe the user or business outcome and define what is deliberately excluded. “Add exports” leaves too much room for interpretation. “Allow workspace administrators to export their own audit events for a selected date range” provides a clearer starting point.

Existing constraints and evidence

Record the contracts the implementation must preserve. Include relevant authorization rules, compatibility requirements, data-retention policies, and performance limits. Link to the files, tests, or documents that establish them.

This is where an agent can do useful investigative work. Ask it to find similar implementations and trace the affected paths. Reviewers can then inspect its evidence instead of relying on a confident summary.

Approach and trade-offs

Explain the proposed design and why it fits the system. If a simpler alternative was rejected, state the reason. The reviewer needs enough detail to challenge the decision without having to reconstruct the author’s private reasoning.

Verification, rollout, and ownership

Define what would demonstrate correctness, how the change reaches users, and what happens if it fails. Identify who owns unresolved decisions and who is responsible for the result, making human accountability explicit. A plan with a consequential unanswered question is still a proposal.

A practical plan-review template

For a change such as an audit export, a short Markdown document can be enough. The values below are illustrative; a real plan should use the system’s actual requirements.

# Plan: add scoped audit exports

## Outcome and non-goals

- Workspace administrators can export their workspace's audit events.
- The export supports a selected date range.
- General-purpose analytics is out of scope.

## Constraints and evidence

- Preserve tenant isolation and current authorization rules.
- Run exports asynchronously using the existing job queue.
- Preserve the current 90-day retention policy.
- Link the relevant authorization tests and queue implementation.

## Proposed approach

- Add an export request endpoint and background job.
- Define authorization checks at request, execution, and download time.
- Store results through the existing encrypted object-storage path.
- Notify the requester when the export is ready.

## Alternatives and trade-offs

- Reuse the job queue to avoid operating another processing system.
- Support CSV first; defer other formats.

## Verification and rollout

- Test cross-tenant requests and revoked permissions.
- Test job retries, partial failures, and download expiry.
- Agree on an export-size limit and test it under load.
- Release behind a feature flag and monitor queue age and failures.
- Document how to stop new exports and handle queued jobs.

## Open decisions and owners

- Security owner: confirm download authentication and expiry.
- Service owner: confirm operational limits and rollout criteria.
- Resolve these decisions before implementing dependent behavior.

The distinction between artifacts also helps keep reviews focused:

Artifact	Main question
Ticket or specification	What problem are we solving, and why?
Implementation plan	How will we solve it within the existing constraints?
Code review	Does the implementation satisfy the agreed intent?
Decision record	Why did we choose this approach, and what changed?

Scale the review to the risk

Planning should make delivery easier. A process that demands a lengthy proposal for a wording fix will quickly lose credibility.

Start with a simple distinction between routine changes and changes with meaningful consequences. Use a short plan for bounded features or refactors. Reserve deeper design review for changes involving sensitive access, persistent data, public contracts, or difficult recovery.

Change	Suitable review
A small, obvious correction	Ordinary implementation and code review
A feature or refactor spanning several parts of the system	Short plan reviewed by the relevant maintainers
A migration, security boundary, or architectural change	Explicit design decisions, named owners, and rollout review

The point is to identify uncertainty and consequences. Line count alone is a weak guide: a small authorization change can deserve more scrutiny than a large mechanical rename.

Give agents a clear execution agreement

An approved plan should specify the work an agent may perform and the conditions that require human input. That gives the agent useful autonomy while keeping consequential decisions visible.

For example, a team might authorize an agent to work on a branch, modify the agreed components, run tests, and open a pull request. Deployment, data deletion, or broader access can remain separate decisions. The agreement should reflect the team’s actual workflow and permissions.

The same plan can support local work by an engineer or execution in an isolated agent environment. Either way, the implementation should reference the reviewed version and explain deviations.

This approach is compatible with existing tooling. Claude Code’s documented practices describe exploring and planning before coding, with planning effort adjusted to the task. GitHub Spec Kit provides a structured process that carries specifications through planning and implementation. A team can adopt the underlying discipline without adopting a particular tool.

Keep code review focused on evidence

Plan approval does not establish that the implementation is correct. The final review still needs to examine the code, the tests, and the behavior that matters in the real system.

Reviewers should compare the result with the agreed constraints. Were authorization rules preserved? Were the failure paths tested? Did the implementation introduce a new dependency or change a customer-facing contract? If it departed from the plan, is the reason recorded and accepted?

Ask for verification evidence that another person can inspect. A statement that “all tests pass” is more useful when it names the tests, distinguishes new coverage from existing coverage, and identifies what was not tested.

A polished plan can contain mistaken assumptions just as easily as polished code can contain defects. Its value comes from making those assumptions easier to examine.

Start with one team and measure the whole workflow

Try this approach with one recurring category of work before expanding it. For example, use short plan reviews for medium-sized features over the next month, then discuss where the process prevented rework and where it added delay.

Track the time spent waiting for a plan review alongside implementation and code-review time. Record significant design changes discovered after coding began, repeated review requests, and operational problems after delivery. Also ask whether someone outside the original conversation can explain the change.

The aim is to improve the team’s decisions and preserve its understanding while taking advantage of faster implementation. If a review step adds effort without changing decisions or improving confidence, simplify it. If the same missing constraint keeps appearing late, bring it into the plan.

Review the plan before you review the diff. Give the team a chance to agree on what should change, why it matters, and how it will be verified before an agent turns the proposal into software.