AI agents often explain their work clearly, but the safest review surface is still the diff. A diff-first review asks the agent to treat changed files, generated artifacts, and deleted lines as primary evidence. The final message can summarize the work, but it should not be the only place where correctness is judged.

This habit matters most for unattended automation. A task can pass through several steps before anyone reads the result: edit, generate, check, build, deploy, and verify. Looking at the actual change set helps catch accidental scope expansion, stale generated files, missing cleanup, or content that should not be published.

What to review before trusting the summary

A lightweight diff review should answer a few operational questions:

  • Did the changed files match the requested scope?
  • Were generated files updated by the documented command rather than hand-edited?
  • Did the agent add only public-safe content and avoid private identifiers, secrets, logs, or local environment details?
  • Are deletions intentional and explained by the task?
  • Do the verification commands cover the files or routes that actually changed?

The review does not need to be heavyweight. The goal is to compare the agent's claims with observable state before treating the run as complete.

Add diff evidence to the receipt

A useful completion receipt can include a short diff summary without copying sensitive content. For example, it can name the content section that changed, the generated index command that ran, the readiness gate, and the live routes verified. If the diff includes private material, the agent should stop and report the blocker instead of publishing or pasting it into the receipt.

Diff-first reviews also make rollbacks easier. When the change set is small and intentional, another operator can revert or repair it without reconstructing the whole session from chat history.

Copyable runbook step

Before marking the task complete, inspect the change set. Confirm that modified, added, generated, and deleted files match the requested scope; summarize the diff in public-safe terms; then run the required checks against the changed surface. Stop with a blocker report if the diff contains secrets, private details, unexplained deletions, or unrelated changes.

Lightweight checklist

  • Is the diff small enough to explain in one or two sentences?
  • Are generated artifacts present only because the approved generator ran?
  • Did the verification step exercise the changed artifact or route?
  • Would a reviewer understand why each changed file moved?
  • Is the final receipt grounded in the diff instead of only the agent's narrative?

Rule of thumb: trust the agent's summary after it matches the diff, not before.