What Is a Review Packet (and Why Agents Should Produce One)?

Quick answer
A review packet is a short document attached to a change that states intent, decisions, risks, and the verification steps the agent ran.
It exists because the diff no longer carries the author’s reasoning: the agent has no memory of why it chose an approach unless it writes one down.
A good packet is four to eight lines: what changed, what was deliberately not changed, what is risky, and the exact commands that verify it.
The packet is a claim set, not a defence. Its value is that every claim can be checked against the diff or a command.
Require it in the pull request template so it is produced before review starts, not after a reviewer asks.

What belongs in a review packet?

Intent in one sentence, the decisions that could reasonably have gone the other way, the parts of the change that are risky, and the commands that verify the result. Optionally, the files the agent deliberately did not touch and why.

Keep it short enough that a reviewer reads it before the diff. A packet longer than the change is a sign the change should be split, or that the agent is padding to look thorough.

## Review packet

Intent: reject expired sessions in the requireUser middleware.
Decisions: refresh tokens stay valid; the login flow is untouched.
Not changed: session storage, cookie flags, logout route.
Risky: the middleware runs on every authenticated request.
Verified: npm test -- auth (12 passed), plus a manual expired-cookie request returning 401.
Open: expired refresh tokens currently fall through to the login flow.

Why can a human diff omit this and an agent diff cannot?

A human author’s reasoning leaks into the work: commit messages, comments, the order of changes, the questions asked in review. An agent starts fresh each session and produces a diff with no such trace. The reasoning existed in the session and then vanished.

That is why the packet is not bureaucracy. It is the missing memory of the change, written at the only moment it is available — while the agent still has the context.

How do you make an agent produce one?

Put the template in the repository and reference it from AGENTS.md, so the instruction is loaded in every session. Ask for the packet as the final step of the task, after tests pass, and refuse to open a pull request without it.

Review the packet for honesty. Agents tend to describe what they intended rather than what they did, so cross-check the “not changed” list against the diff. That list is the most useful part and the easiest to get wrong.

What makes a packet useful rather than decorative?

Specificity and falsifiability. “Improved error handling” cannot be checked; “returns 400 instead of 500 when the body is missing a field, covered by test/api/validation.test.ts” can. Every line should be something a reviewer could disprove.

The verification commands are the highest-value line. If the reviewer can run one command and see the same result, the packet has done its job. If the commands do not reproduce, that is the finding.

Where this bites vibecoders
An agent asked for a summary will produce a confident paragraph that restates the task and omits the risk. Give it the template and require the “not changed” and “verified” lines; those two force it to compare its work against the boundary.

Where AI coding assistants get this wrong

Writing a summary that restates the prompt instead of describing the diff.
Omitting the “not changed” list, which is where scope creep hides.
Claiming tests passed without the command and the output.
Describing intent in the past tense as if it were evidence.
Producing the packet after review comments, tailored to them.
Padding the packet until nobody reads it.

Checklist

Add the packet template to the pull request template.
Reference it from AGENTS.md.
Require intent, decisions, not-changed, risks, and commands.
Check the not-changed list against the diff.
Run the verification commands yourself.
Reject packets that restate the prompt.

FAQ

Is a review packet the same as a pull request description?

It can be the description, or the first section of it. The difference is structure: a description is prose for a reader, while a packet is a set of checkable claims. GitHub pull request templates are a practical place to enforce the structure.

Does this slow the agent down?

It adds a step at the end of the task, when the context is already loaded. In exchange, review starts with the boundary and the verification path instead of a cold read. For any change larger than a few lines, the trade is favourable.

What if the agent cannot verify something?

That is what the open-questions line is for. An honest “could not verify without a browser” is more useful than a fabricated assurance. Record it and verify manually, or add the missing automated check.

Should the packet be committed?

Keep it in the pull request rather than the codebase, unless the project keeps decision records. The durable value is in review history and the commit messages; a packet committed to the repository goes stale immediately.