What a reviewer needs from an agent

Reviewing agent work is different from reviewing a colleague who will be in the next stand-up. The reviewer cannot count on memory, intent or a hallway correction. They get a task, a branch, a pull request and whatever proof the agent chose to leave behind. If those artefacts do not answer the obvious questions, the reviewer must either reject the work or accept risk they cannot see.

That changes what good delivery looks like. An agent does not help a reviewer by sounding confident. It helps by making every claim inspectable. The work should say what changed, where it changed, how it was checked, what evidence backs the check, and what remains uncertain. That package is the difference between review and archaeology.

What does a reviewer need before opening the diff?

The reviewer first needs orientation. A task title and a branch name should tell the same story. The pull request should repeat that scope in plain language, then point to the exact files where the answer lives. This is basic workflow hygiene, but it matters more with agents because the agent will not be present when the reviewer gets confused.

GitHub describes pull requests as the place where proposed changes are discussed before merging. For agent work, that discussion surface has to carry more context than usual. The branch should include the task key. The pull request title should include the same key. The body should name the definition of done, the main artefact produced, and the checks run. If the change is an article, the body should link the article file. If the change is a migration, it should link the migration and the rollback note. If the change is code, it should link the test log or build output. The same habit applies to llms.txt, where the contract must be visible.

A reviewer should never have to ask, “What was this agent trying to do?” That answer belongs in the first screen.

What evidence makes an agent claim reviewable?

Evidence has to be closer to the work than the agent’s summary. A sentence that says the article exists is weak. The markdown file is stronger. A rendered PNG of that file is stronger still because the reviewer can scan it without checking out the branch. The same pattern holds for code: a test command in prose is useful, but the captured output is better, and a failing-then-fixed record is better than a green-only story that hides the path.

The useful evidence bundle usually has three layers. The first is the artefact itself: the file, migration, design document, generated report or changed code. The second is a view of the artefact as a user or reviewer will encounter it: a screenshot, rendered page, compiled output or markdown render. The third is verification: logs, checksums, test results, linter output, or a command list that can be rerun.

This is also where AI risk guidance becomes practical. NIST AI RMF 1.0 stresses measurement, documentation and governance around AI system behaviour. OWASP’s GenAI work focuses on boundaries, inputs and unsafe actions, the same reason read controls do not govern write paths. Show the evidence at the boundary where the agent acted.

How should verification be written?

Verification should be executable enough that a reviewer can repeat it without interviewing the agent. “Tested locally” does not meet that bar. “Ran pnpm build on commit abc123, which completed with content validation and HTML checks” is reviewable. It names the command, the scope and the result. If the project has no applicable automated test, the proof should say what was inspected manually and why that is sufficient for the task.

Good verification also separates the claim from the observation. The claim might be that an article is at least 700 words. The observation should name the word-count command or script result. The claim might be that the branch was pushed. The observation should name the pushed branch and pull request. The claim might be that no website publication was required. The observation should point back to the definition of done.

This discipline protects both sides. The reviewer gets a route through the evidence. The agent avoids being judged on vibes. When a check fails, the same record should say what failed and how it was fixed. A clean final sweep matters, but only after the trail shows the work was actually examined.

What limits should an agent disclose?

Reviewers need limits as much as successes. An agent that reports only green checks forces the reviewer to search for missing scope. A better handoff states the boundaries directly: which files were touched, which related files were left alone, which checks were skipped, and why. If a dependency install failed, that fact belongs in the proof. If a browser screenshot was impossible and a text render was used instead, that trade-off belongs in the proof too.

This is inventory control. Google Engineering Practices asks reviewers to judge whether a change improves the codebase and fits the intended design. They can only make that judgement when the submission exposes its edges. A limitation might be harmless, such as “publishing was out of scope”. It might be serious, such as “the integration test runner could not be installed”. The reviewer needs to know which kind it is before approval.

Agents should also avoid decorative certainty. Phrases like “all requirements satisfied” are useful only when each requirement is listed with evidence. Otherwise they ask the reviewer to trust the same system whose work is under inspection.

What does a good review packet look like?

A complete packet is small, boring and easy to audit. It starts with the task key and definition of done. It names the branch and pull request. It lists the delivered artefacts. It attaches the artefact itself and a rendered view when that is practical. It records verification commands and their observed output. It states any limits without burying them under optimism.

For an article task, the packet might say: markdown article added at content/posts/example.md; word count checked with a shell command; content validation and prose checks run; branch pushed; pull request opened; proof attached with the markdown file and rendered PNG. A reviewer can approve or reject that packet quickly because every sentence points to something inspectable.

For a code task, the shape is similar: changed files, reason for the change, tests run, logs attached, screenshots for visible behaviour, and any skipped checks called out. The format changes, but the reviewer need stays constant.

Agent work earns trust by reducing the amount of trust required. The reviewer should not have to believe the agent was careful. They should be able to see the trail, rerun the checks and decide from evidence.