AI Agent Diff Review: Comparing Proposed Changes Before Approval

An AI agent’s final answer can hide the most important part of the work: what changed. A polished summary may say that records were cleaned, code was updated, a draft was improved, or a configuration was adjusted. That may be true, but it is not enough for approval. A reviewer needs to see the difference between the previous state and the proposed state.

Diff review is the practice of making agent changes visible before they become trusted. In software, the word diff has a familiar meaning: lines removed, lines added, files touched. The same idea applies beyond code. A data cleanup can show before-and-after rows. A customer reply can show the old draft beside the proposed revision. A policy update can show changed clauses. A schedule change can show what moved, why, and what dependencies follow.

This topic belongs beside Human Review for AI Agents and AI Agent Artifact Design . Human review needs evidence. Artifact design shapes that evidence into something a person can inspect. Diff review focuses on the comparison itself, because approval is much easier when the change is visible instead of merely described.

A proposal should not masquerade as a finished state

Agents often write in the language of completion. They say the issue is fixed, the draft is ready, or the dataset is cleaned. That language can be useful after verification, but it is risky before review. A proposed change is not the same as an accepted change.

The workflow should preserve that distinction. The agent can prepare a patch, a revised document, a normalized table, or a changed configuration. It can explain why the change appears correct. It can run validation. But until the review boundary has been crossed, the artifact is still proposed work.

AI Agent Approval Scopes makes this boundary explicit. Diff review gives the approver something concrete to approve. A vague yes to a summary is weak. A yes to a named change set, with visible before-and-after evidence, is stronger. It gives the system a record of what was authorized and gives the reviewer a fair chance to notice problems.

The difference matters when work resumes later. If an agent changes the proposal after approval, the old approval should not automatically follow. The diff has changed, so the approval target has changed.

The baseline matters too. A patch prepared against yesterday’s record may no longer describe the effect of applying it today. Identify the baseline and proposed version, then recheck the relevant current state before execution. If either the proposal or a material fact has changed, return it for review under the workflow’s rules. For consequential actions, the execution path must enforce that boundary; a version or hash is useful only if it covers the meaningful content and is actually checked. OWASP’s transaction authorization guidance describes related safeguards for significant transaction data and execution.

Review starts with scope

A good diff begins by making the footprint visible. Which files, records, fields, pages, messages, or settings changed? Which nearby materials were read but not changed? Which expected areas were intentionally left alone? The reviewer should not have to infer scope from a broad success statement.

This is where AI Agent Acceptance Criteria helps. Acceptance criteria define what done means. Diff scope shows whether the proposed work stayed inside that definition. If the task was to update one onboarding page and the diff touches global navigation, the review can catch that early. If the task was to clean duplicate records and the diff changes unrelated fields, the reviewer can ask why.

Scope also protects the agent. A small, clear diff is easier to trust. A large diff with unclear motivation forces the reviewer to become a detective. When agents create detective work, they lose much of the time they were supposed to save.

Build a review packet

For a record correction, a useful packet might say: “In the staging customer table, change record 482’s status from pending to active; all other fields remain unchanged. The signed activation record supports the change. The record was last read at version 17. No production update has been made.” It should link to the restricted evidence, show the actual before-and-after values, and name any check that failed or could not run. The example identifiers and status are illustrative, not a rule for deciding when to activate a customer.

The reviewer can then check that record 482 is the intended target, the evidence supports the new value, the untouched fields are correct, and version 17 is still current. The decision should say whether it authorizes only the proposed edit or also its execution, and in which environment. If the record changed since the snapshot, refresh the comparison and resolve the conflict before applying it. A sample of a batch helps a reviewer inspect examples, but it cannot prove that every row is correct; provide the full affected set through an appropriate access-controlled view and report aggregate checks and exceptions.

For a batch, identify rows by stable keys rather than their display order. Show additions and deletions as well as changed fields, and distinguish a missing value from an empty string or zero when that distinction matters. Include the selection rule, number of records examined and affected, and any duplicates, conflicts, or excluded records. A summary such as “100 rows cleaned” cannot show whether the right 100 rows were selected. If the full set is too large for the review screen, make it available in a protected export or paginated view and say how the reviewer can find the exceptions.

For code, GitHub’s pull request review guide recommends inspecting changes file by file and commenting on specific changes. Whatever tool a team uses, include additions, deletions, renames, and configuration changes in the inventory. Check for untracked or omitted files, truncated views, generated output, and binary assets that a text diff cannot explain. A rendered preview or an explicit description may be needed alongside the patch. A diff can show a change without showing its downstream effects, so inspect the surrounding behavior and dependencies as well.

Check which code states are being compared

Name the base commit and proposed commit in the handoff. In Git, git diff BASE HEAD compares those two committed snapshots; replace BASE with the actual baseline commit. It does not include later uncommitted work. For a local working tree, git diff shows unstaged tracked changes and git diff --cached shows staged changes; git status --short also identifies untracked files, whose contents need separate inspection. These views answer different questions, as the Git diff documentation explains. Do not assume one view contains the entire proposal.

If the target branch moves, compare against the current target and check the result that would actually be merged. Resolve conflicts and rerun relevant checks on the resulting version. The reviewer may need to inspect and approve a revised proposal, even when the original patch looked sound in isolation. Keep unrelated local changes out of the proposed change set and say when the review view cannot show an asset or generated result.

Bind the decision to the action

Record the reviewer, decision and time, the exact proposal version, the target and environment, and whether the decision covers execution. Preserve the validation results and any conditions or expiration required by the workflow. A link to a mutable draft alone is a poor identifier: it may later show different content. A version or digest can identify the reviewed artifact, provided it covers the relevant change and the execution system checks it.

For a record update, use a conditional write against the reviewed revision when the system supports it. For example, HTTP If-Match lets a server reject a modification if the entity tag no longer matches. A separate read immediately before an unconditional write still leaves a window for another update. If the condition fails, fetch the current state, rebuild the comparison, and follow the workflow’s review rules; do not silently overwrite it. Where conditional writes are unavailable, use the system’s locking or manual conflict process and state its limits. See AI Agent Concurrency, Locks, and Leases for those coordination choices.

After an authorized action, record the outcome separately from the approval: what was applied, where, the resulting version or action ID if available, and any failure or partial completion. Verify the resulting state where practical. Approval of a proposal is evidence of a decision, not proof that execution succeeded.

The explanation should follow the diff

Agent explanations are useful when they point at the change. They are weaker when they float above it. “Improved clarity” is not enough. What sentence changed? What ambiguity was removed? What source supports the new wording? “Fixed the bug” is not enough. What condition failed, what changed in the code, and what test or reproduction supports the fix?

The best review explanations are anchored. They describe the reason for a change near the change itself or in a summary that names the affected area. They do not need to narrate every obvious edit. They should focus on decisions a reviewer might question: why this record was merged, why this exception was preserved, why this file was touched, why this source outranked another.

AI Agent Output Verification provides the next layer. A diff can show what changed, but verification asks whether the change satisfies the task. The two should travel together. For code, report the relevant tests and their results, or explain what was not tested. For a policy rewrite, link the governing source and version. For a data correction, explain the validation rules, exceptions, and coverage. Passing checks support a decision; they do not establish that the change is correct in every circumstance.

Diffs should include omissions when omissions matter

Sometimes the most important review fact is what the agent did not change. A task may mention several possible records, but only two should be updated. A document may contain many style issues, but only one section is in scope. A bug report may tempt a broad refactor, but the safe fix is narrow.

An agent can help review by naming material it inspected and left unchanged when that omission is meaningful. This should not become theatrical logging. The reviewer does not need a list of every file opened. But if a likely candidate was skipped, the handoff should say why. The skipped area may already be correct, out of scope, blocked by missing evidence, or waiting for a separate owner.

This habit is related to AI Agent Status Updates . A good status update reports progress and blockers. A good diff review reports change and restraint. Both help humans understand the shape of the work without replaying every step.

Non-code workflows need diff language too

Many teams reserve diff thinking for software and then lose it in operations. That is a mistake. Operations work often needs before-and-after review even more because the systems involved may not have natural pull requests.

A support agent proposing a customer message can show the source facts, the draft, and the parts that were deliberately softened or left out. A finance agent preparing an adjustment can show the original record, proposed value, approval reason, and fields untouched. A research agent updating a brief can show which claims changed because a newer source superseded an older one. A scheduling agent can show the old time, new time, conflict checked, and notification still pending.

The form changes, but the principle does not. A comparison gives reviewers a more concrete basis for deciding whether to approve.

Before sharing a diff, consider who can see it. Before-and-after values can expose personal data, credentials, or confidential business information, including material that was deleted from the proposed version. Redact unnecessary details and link to protected evidence where a reviewer needs the full context. Redaction should not conceal a decision-relevant change; if the reviewer cannot inspect what matters, route the review to someone with appropriate access. AI Agent Data Boundaries covers this tradeoff in more detail.

Beware of cosmetic noise

A diff can become unusable when the agent changes too much at once. Broad reformatting, reordered fields, regenerated files, and automatic cleanup can bury the meaningful change. The reviewer sees a large diff and cannot tell where the real decision happened.

This is one reason AI Agent Workspace Hygiene matters. A contained workspace produces cleaner diffs. It also supports AI Agent Rollback and Recovery , because a narrow change can be undone with less collateral confusion.

Agents should prefer stable formatting unless the task is formatting. They should avoid rewriting unrelated sections to match their own style. They should separate mechanical cleanup from behavioral or policy changes when the workflow permits it. The goal is not a tiny diff at all costs. The goal is a diff where the important changes are visible.

Approval is easier when the diff tells the truth

A mature agent workflow does not ask humans to approve a mood. It asks them to approve a visible proposal. The diff shows the proposal, the explanation gives the reason, the evidence supports the reason, and the validation shows the result.

That structure changes the review relationship. The human is no longer stuck reading a confident agent summary and wondering what happened underneath. The human can inspect the material that matters. The agent, in turn, is rewarded for making work reviewable rather than merely making it sound done.

Diff review is not only a technical artifact. It is a trust habit. It keeps proposed work in the open until someone or some rule has decided that the change should become real.