Diffs deserve a rehearsal before anyone merges them

Two explanations of one diff reveal different engineering habits

A diff rarely fails review because its syntax is unreadable. It fails because the explanation attached to it hides a decision, overstates a guarantee, or passes over the one line that changes runtime behavior. Asking a coding agent to explain a diff before merge is therefore not a request for a summary. It is a request for a rehearsal of the review you are about to perform, delivered early enough to be argued with.

The rehearsal becomes genuinely useful when two accounts of the same change are placed next to each other. Read explanations side by side and confident vagueness stops hiding. One account says the refactor preserves behavior, while the other names the exact branch where it does not. One lists the files it touched, while the other traces data from entry point to persistence and back. The difference is not eloquence. It is the amount of verifiable structure each agent chose to expose.

That structure can be demanded rather than hoped for. Decide in advance what a serious explanation must contain, then score both accounts against the same list. A reviewer who writes the criteria down before the first answer arrives is far less likely to be charmed by the second. The habit also travels well: the same rubric works whether the change comes from a human pair, a junior engineer, or an agent proposing a patch at the end of a long session.

Explicit criteria keep the side-by-side reading honest and repeatable

Criteria matter because they force both accounts to answer identical questions. Without them, the more fluent answer wins by default, and fluency is exactly the property that makes an agent dangerous during review. With them, a reviewer can point at a missing row instead of nursing a vague unease. The judgment becomes repeatable across reviewers, which is the difference between a team habit and an individual superstition.

• Scope: the explanation names every file and symbol the change touches, and admits the alternative it deliberately declined to make.
• Causality: each behavioral claim is tied to a specific line, condition, or ordering effect, never to the general spirit of the change.
• Risk: the explanation states the failure modes it considered and, crucially, the ones it cannot rule out.
• Evidence: claims about tests, metrics, or compatibility point to concrete artifacts a reviewer can inspect without trusting the prose.
• Reversibility: the explanation says how the change would be undone and whether data written before the rollback remains valid.
• Boundaries: the explanation separates what the diff does today from what a follow-up must still do.

Six rows are enough for most repositories, and a small rubric is one people actually use. Score each row as met, partly met, or missing, then treat missing risk and missing causality as blockers rather than comments. Two agents will often satisfy the same rows with different depth, and that gap is the finding. The shallower account is not wrong so much as unready, and unready explanations are the ones that turn into production incidents three weeks after the merge.

An honest explanation names every risk it cannot rule out

The most valuable sentence in an agent explanation is usually a refusal. A good account says it cannot determine whether the cache key changes when the input schema gains a field, or whether an older client tolerates the new response shape. That admission tells the reviewer where to spend attention, and it costs the agent nothing but candor. Explanations that answer every question confidently are the ones to distrust, because real diffs always sit on top of assumptions the diff itself does not express.

Good rehearsals surface implicit invariants. Ordering guarantees, transaction boundaries, retry semantics, idempotency keys, and the lifetime of a background job are rarely visible in the changed lines, yet they are where regressions live. Ask the agent to list the invariants its change relies on, and to say which of them it verified. The difference between an invariant that is tested and an invariant that is assumed is usually a single paragraph, and that paragraph is worth more than the rest of the summary.

Concurrency and data shape changes deserve their own scrutiny. A migration that is safe forward is not automatically safe during a rolling deploy, and an agent should say so rather than describe the final state. The same discipline applies to cost: a system that bills pay as you go from the token counts the provider reports, with cache reads and cache writes priced separately, rewards explanations that are exact instead of padded. Precision is a habit that shows up everywhere at once.

Behavioral claims need evidence rather than confident sentences

An explanation is a set of claims, and claims need witnesses. When an agent asserts that a function still handles empty input, the reviewer should be able to find the test that exercises empty input and see the assertion that would fail otherwise. When it asserts compatibility, the reviewer should see the range being claimed and the reason for it. Tests that only cover the happy path support only happy path claims, and an explanation that cites them for more is overreaching.

Compare the evidence, not just the conclusions. One account may cite a passing suite of shallow tests while another describes a targeted reproduction, a failing case before the fix, and the exact assertion that now passes. Side by side, the second account is auditable and the first is merely reassuring. Auditable explanations let a skeptical reviewer disagree in public, which is the entire point of code review.

Model choice affects this texture more than teams expect. Running the same prompt through one capable model and then a second one is a cheap way to see what your rubric is catching. Naming the model matters as much as asking the question, because a silent substitution makes every comparison meaningless. That is the principle behind BestRelay, the publisher of this article: it is a quality-first API relay that forwards each request to the official model named in it, with no substitution, so an explanation produced under a known model label stays comparable over time. It works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK, so the same rehearsal prompt can live in the tooling a team already uses. Create a BestRelay account if that traceability is what your review process is missing. Members who invite colleagues also earn a referral commission when those colleagues top up.

A short rehearsal ritual protects every merge you approve

The ritual can be small enough to survive a busy week. Ask for the explanation before reading the diff, so the agent cannot simply mirror your edits back at you. Read the two accounts side by side, score them against the rubric, and then open the diff to confirm which account matched reality. Record the score beside the pull request, because the pattern across a month of merges reveals which parts of your system agents consistently misunderstand.

Disagreements are the most informative output. When an agent explanation and the diff diverge, one of three things is true: the explanation is lazy, the change is more subtle than its author believed, or the repository carries knowledge that lives outside the code. Each possibility calls for a different response, and the rehearsal makes the diagnosis visible before anything ships. Teams that adopt the habit report a quieter consequence as well. Agents produce better first explanations when the review culture rewards specific risks and punishes confident emptiness, and that feedback loop compounds.

Merge less on trust and more on evidence. A diff that arrives with a rehearsal, a rubric score, and a list of what remains unproven has already done half of your job. The other half is the pleasant part: reading code that a careful explanation has already told you where to look for trouble.