The Pull Request Has to Carry the Session You Did Not Watch

You did not see the work happen, there is no track record, and there is nobody to ask. Half of what review normally runs on is missing.

Review normally leans on the author, and there is no author

Reviewing a colleague's pull request, you are not only reading the diff. You are drawing on a set of priors that arrive with it: this person is careful about error handling, they have been in this module before, they said in standup they were unsure about the caching bit, and if something looks strange there is probably a reason you can ask about.

None of that is available for work produced by an unsupervised agent. You did not watch the session, the author has no track record in the sense that matters, and there is nobody to ask afterwards. The diff arrives without the half of the information you normally use.

Which means the pull request itself has to carry what the session would have told you. Not as documentation ceremony — as the input review needs to function at all. A companion piece, reviewing agent-authored code, covers what to look for in the code; this is about what has to arrive alongside it.

What the description has to contain

## Task
<the brief, verbatim>

## Done conditions
`scripts/done.sh` — PASSED (output attached)
Task-specific assertions: legacy path removed, new middleware wired.

## Decisions
- Used the existing event bus rather than adding a queue. Rejected the
  queue because sync/inventory.ts already subscribes and adding a second
  mechanism would give us two.
- Kept `pollIntervalMs` in the config file, unused, rather than removing
  it — see "not verified" below.

## Not verified
- Whether `pollIntervalMs` is read by the deployment templates. I cannot
  see that repository. If it is, removing the key later is a breaking
  change and this PR does not remove it.
- Behaviour under duplicate event delivery. The handler looks idempotent
  but there is no test for it and I did not add one.

## Out of scope
- The retry semantics in #4412.
- sync/inventory.ts, which has the same pattern and the same issue.

Four sections. The task verbatim, so you can check the work against what was asked rather than against what you remember asking. The done conditions and their result. The decisions with rejected alternatives. And the two sections that do the most work.

"Not verified" is the highest-value section in the document

It is also the one no agent produces without being asked, because the default register of generated prose is uniform confidence.

What goes in it: things outside the repository the agent could not check, behaviours it reasoned about but did not test, assumptions it made about how something is used elsewhere. In the example above, the deployment-template question is exactly the kind of thing that causes an incident three weeks later, and it is entirely invisible in the diff.

Ask for it explicitly and insist on it being non-empty. An agent that reports nothing unverified on a substantial change has either not thought about it or is telling you what it thinks you want, and both warrant a follow-up question.

The confidence problem

A human pull request signals uncertainty through texture. A hedge in a comment, a slightly apologetic note, a question in the description, a TODO where they were not sure. Reviewers read those signals without noticing and allocate attention accordingly.

Agent output has flat texture. The line it was confident about and the line it guessed at are written identically, in the same register, with the same apparent conviction. So the reviewer's usual mechanism for deciding where to look hard is gone, and the natural fallback — read everything with equal care — does not survive contact with a four-hundred-line diff.

Ask for the diff ranked by risk

The workable substitute is to have the agent do the ranking, explicitly and separately from the code.

"List the changes you are least confident about, most first, with why" is a prompt that produces a genuinely useful ordering. It is not perfectly calibrated and it does not need to be: it needs to be better than reading top to bottom, which it comfortably is. The top two or three items are usually the places a careful reviewer would have ended up anyway, reached in thirty seconds instead of twenty minutes.

Review in the right order

Conditions, decisions, then diff. In that order, and stop early where you can.

If the done conditions did not pass, there is nothing to review yet. If a decision is wrong, the diff implementing it is irrelevant. Only when the target was met and the approach is right does reading the code become the useful activity. Reviewers who start with the diff routinely spend twenty minutes on the implementation of an approach they then reject.

Do not trust the summary; re-run the check

The description says the conditions passed. That claim was written by the thing being reviewed, and the failure mode is not dishonesty but optimism: a check that partially passed, a suite run with a filter, a command whose exit code was not actually examined.

So the check runs in CI, from the branch, as the gate — not as a paste in the description. The description tells you what the agent believes; CI tells you what is true. That separation is the whole point of CI gating for agent pull requests, and it is the reason the description can be treated as a helpful narrative rather than as evidence.

Commit structure is part of the deliverable

A single commit containing everything is the default and it is the worst case for review. Ask for the work split by concern — the mechanical rename separate from the behaviour change, the test additions separate from the fix — because that lets you review each part at the right depth.

A four-hundred-line diff where three hundred and eighty lines are a mechanical rename and twenty are the actual change is a twenty-line review once the commits are separated, and a four-hundred-line review when they are not. The agent can do the separation on request and will not do it by default.

The large diff problem does not have a clever solution

Sometimes the change is genuinely large. There is no technique that makes reviewing a thousand lines cheap, and the honest options are: split it into several pull requests, review only the risky subset identified by the ranking and accept the rest on the strength of the tests, or read the whole thing and accept that it will take an hour.

What does not work is pretending. The failure mode of large agent-authored pull requests is an approval that everyone treats as review and nobody performed, and it is worse than an explicit "I read the three risky files and trusted the tests for the rest", which at least records what happened.

Latency is a correctness issue, not just a courtesy

A branch that sits for a week is reviewed against a main branch that has moved, and the rebase that follows is itself unreviewed work. Agent-produced branches accumulate faster than human ones and therefore rot faster, which makes review latency a technical problem rather than a scheduling one.

The practical rule is that the queue depth should be bounded by review capacity rather than by generation capacity. What that implies for how many agents you should run at once is the subject of parallel agents and the serial reviewer.

Reject rather than iterate, more often

With a colleague, iterating on a pull request is usually right: they understand the context, the fix is small, and the back-and-forth is cheap. With agent work the calculation shifts, because regenerating from a corrected brief is often cheaper than three rounds of review comments.

The signal is the kind of problem. Wrong approach, missing context, a misread requirement — reject and re-run with a better brief. A specific mistake in otherwise correct work — comment and iterate. The mistake is treating everything as iterable because that is the habit, and ending up having a five-comment conversation with something that would have produced better work from a better instruction.

Watch what you are learning about your own repository

A recurring pattern in these reviews is worth attending to. If the "not verified" section keeps naming the same thing — a configuration held elsewhere, an undocumented contract, a test suite that does not cover a behaviour everyone relies on — that is not an agent limitation. It is a gap in your repository that human contributors have been silently working around.

Fixing it improves every future review, agent-authored or not, and these reviews are unusually good at surfacing it because the agent has no tribal knowledge to compensate with.

Keep a note of what review costs

Worth tracking, roughly, for a few weeks: how long each agent pull request took to review and how many needed a second round. Not as a metric to manage, but because the answer determines whether the whole arrangement is a gain.

An hour of generation that costs forty minutes of review and lands first time is excellent. The same generation costing forty minutes of review across three rounds is worse than doing the work yourself, and it will not feel that way, because each individual round felt short. The arithmetic is the thing that tells you, and nobody does it unless they decide to.

Two reviewers is a different arrangement

One structural option worth knowing about. Because the pull request is carrying the session, it is unusually reviewable by someone who was not involved at all — there is no "you had to be there" context to transfer.

That makes agent-authored work easier than human work to spread across a team, which is a mild upside to an otherwise harder review. It also means the obvious efficiency — the person who wrote the brief reviews the result — is not the only option, and having someone else read it catches the class of problem where the brief itself was wrong.

Sign-off should say what was actually done

A last practice worth adopting. An approval comment that says which parts were read closely, which were accepted on the strength of the tests, and which of the "not verified" items were checked, takes fifteen seconds to write and makes the record honest.

Its value shows up during an incident, when the question is what anyone actually looked at. A bare approval implies a complete review that almost never happened; a specific one implies exactly what it says, and nobody has to reconstruct it later from a timestamp.

The pattern to be most alert to is the pull request that is easy to approve. Agent output reads well, the description is organised, the tests pass, and nothing in it invites a question. That is precisely the condition under which review adds least, and it is the condition most agent pull requests are in. Fluency is not evidence, and a document engineered to be easy to accept deserves the extra thirty seconds that a scrappier one would have prompted naturally.