A consequential PR is ready to merge when its behaviour, evidence, and escape route can be explained—not when the tool or person that produced the diff can be identified.
The PR has two approvals, a green build, and a diff nobody in the room can explain past its local edits. Ask what happens when the remote call times out after the request arrives, and the answers turn into guesses: perhaps the retry is safe; perhaps the record already exists; perhaps on-call can undo it.
That is not a review problem caused by AI. It is a review problem made easier to miss when a generated patch arrives fluent enough to look finished. The important question isn’t who typed the lines. It is whether the team can state what the change claims to do, show the evidence that supports that claim, and describe what happens when reality disagrees.
Code review should judge behavioural claims, evidence, and containment—not the identity of the typist.
The approved mystery
A consequential change has an effect outside its own file: it changes a contract, moves money or data, alters access, schedules work, or changes how a system behaves under failure. Its diff may be tidy while its behaviour remains opaque.
That opacity is expensive after a merge. A reviewer who cannot explain the change leaves the next engineer to reconstruct intent from branches, logs, tests, and assumptions buried in adjacent code. The on-call engineer then inherits a symptom without a failure model: a duplicate notification, a missing update, an incompatible response, or a retry loop that keeps making the situation worse.
AI-assisted work makes this pattern more likely because a tool can produce several locally plausible decisions in one pass. A helper name suggests a policy, a guard suggests a boundary, and a passing test suggests coverage. None of those things prove that the decisions compose into the behaviour the system needs.
The same is true of copied code and hurried human-written code. AI doesn’t create the obligation to understand a consequential change; it removes some of the friction that used to expose misunderstanding before review.
The patch without intent
A diff describes implementation. It does not describe intent.
Consider a patch that retries a remote request. The implementation might add a retry wrapper, preserve a timeout, and pass the same payload on each attempt. Each move can look reasonable in isolation. The missing question is whether the remote operation is safe to repeat after a response is lost.
That question depends on an invariant: perhaps the operation must create no more than one external side effect for a given business action. The diff cannot establish that invariant by itself. Nor can a test named retriesOnTimeout if it only proves that a second HTTP request was sent.
An author should be able to say, in plain engineering terms: “This change permits a retry after an uncertain response, and it remains safe because this key defines the idempotency boundary.” If they can’t, the patch may still be correct, but the team does not yet have a reviewable claim.
Keep consequential changes small enough that their author can explain the behaviour end to end. This adds authoring effort and can slow a merge. It also reduces reviewer archaeology and gives on-call a starting model when the system breaks at an inconvenient hour.
The hidden boundaries
Generated patches often conceal unstated invariants at boundaries: between request and persistence, persistence and publication, caller and API contract, or a retry loop and an external side effect. Those boundaries are where locally sensible code becomes globally wrong.
A retry is the familiar example. A caller sends a request. The remote service performs the side effect. The response disappears in transit. From the caller’s point of view, the outcome is uncertain. Retrying may recover a lost success—or may perform the side effect twice.
The issue isn’t whether retries are good. They often improve recovery from transient failures. The trade-off is that recovery behaviour must be constrained by the operation’s semantics. If the author cannot name the constraint, reviewers are left to infer it from implementation details that may not encode it completely.
flowchart LR
A[Intent and invariant note] --> B[Implementation diff]
B --> C[Focused test or reproducible command]
C --> D[Contract and schema behaviour]
D --> E[Production signal]
E --> F[Containment or rollback]
F -. informs the next change .-> A
This path is not a sequence of approvals. It is a set of cross-checks. The intent note says what must remain true; the diff says how the author attempted it; executable evidence shows one path behaving as expected; the contract shows what neighbouring systems can rely on; and production evidence plus rollback answers what the team will see and do if the claim fails.
The evidence trail
No single evidence surface is enough for every consequential change. Each answers a different question and has a different blind spot.
| Evidence surface | What it establishes | Its blind spot |
|---|---|---|
| Intent or invariant note | The behaviour that must remain true | It doesn’t prove implementation matches it |
| Diff | The implementation changed | It doesn’t reveal unstated intent |
| Focused test or command | A defined path can execute | It may miss contracts and failure timing |
| Contract, schema, or API behaviour | What callers and consumers observe | It may not show operational recovery |
| Production signal | What failure or success looks like live | It often arrives after impact |
| Containment or rollback | How harm can be limited | It doesn’t make the original claim correct |
The reviewer’s task is not to demand every row as ceremony. It is to ask which rows are needed to expose the risk in this change. A migration may need a schema and rollback plan. A permission change may need an explicit invariant and a reproducible access check. A remote write with retries needs evidence at both the idempotency boundary and the observable failure path.
Evidence is strongest when two surfaces can disagree usefully. A written invariant can expose a test that proves the wrong thing. A contract check can expose a diff that preserves internal behaviour while changing what callers receive. A rollback plan can expose that the change was never safely containable.
This is the practical skill behind adopting AI workflows deliberately: choose work where verification is possible, then make verification part of the change rather than an afterthought.
The reviewable change
For a retrying remote operation, the author should walk the reviewer through the uncertain-response case rather than merely point at the retry helper.
flowchart TD
A[Caller sends remote request] --> B[Remote service performs side effect]
B --> C{Response reaches caller?}
C -->|Yes| D[Record success]
C -->|No: response lost| E[Caller sees timeout]
E --> F[Retry decision]
F --> G{Idempotency boundary recorded and checked?}
G -->|No| H[Duplicate side-effect risk]
G -->|Yes| I[Existing operation returned or retry safely handled]
H --> J[Review: show duplicate prevention]
I --> K[Review: show contract, signal, and rollback]
The diagram’s point is not that every service needs the same idempotency design. It is that the uncertain response creates a branch the happy-path diff can hide. Review should expose that branch with concrete checks:
- State the invariant: what makes two attempts the same business operation?
- Show the executable case: run a focused test or command that simulates the lost-response path where possible.
- Name the contract: explain what the caller receives on a repeated request and what downstream consumers observe.
- Expose the signal: identify the log, event, counter, or record that distinguishes a safe retry from a duplicate effect.
- Describe containment: say whether the change can be disabled, rolled back, or compensated without creating a second failure.
A reviewer may understand the code well enough to repair it themselves. That is not a reason to merge an unexplained patch. If the author cannot explain the behaviour, the team has discovered either a learning gap or a change that is too large to review safely. Pair on the explanation, reduce the scope, or split the PR until the claim becomes legible.
This is also why boring architecture helps when systems become hard to reason about. Predictable boundaries do not remove failure modes, but they make invariants, observations, and rollback paths easier to state before an incident forces the issue.
The cost is real: explanation takes time, and a reviewer may hold a merge while the author writes a short note or adds a focused check. The alternative is not faster understanding. It is deferred understanding, paid later by reviewers and on-call engineers under worse conditions.
FAQ
Do small changes need this much evidence?
No. The level of evidence should follow the consequence, not the number of changed lines. A wording fix or isolated refactor may need only a clear diff and ordinary tests; a three-line change to authorization, retries, or data handling may need an invariant and a containment story.
What if the reviewer understands the code but the author cannot explain it?
Don’t turn review into an oral exam. Treat it as a signal that the author needs to trace the behaviour with someone else, or that the change should be split. The reviewer can help build the explanation, but should not become the only person who has it.
Aren’t focused tests enough without a written intent note?
A focused test can prove a chosen example, but it cannot tell a reviewer whether the example is the right behavioural claim. The note gives the test a target; the test then gives the note executable support.
Does this apply to code written entirely by humans?
Yes. It applies to copied snippets, framework-generated scaffolding, rushed fixes, and careful handwritten code alike. AI is relevant because it changes the volume and fluency of proposed code, not because it changes the standard of engineering judgement.
For the next consequential PR, require a short intent-and-invariant note, one focused piece of executable evidence, and a named observable rollback or containment path before approval; use it as the first exercise in your team’s AI training practice.