What evidence should come with an agent-written pull request?

An agent reports that a change is complete, but the reviewer still has to find the diff, work out what was tested, and reconstruct the original request. A useful handoff packages that evidence with the change so review can begin with the behavior that matters.

For a small team, this is a shared practice: the implementer prepares the evidence, a reviewer inspects it, and a named person decides whether the work is accepted. It applies to Claude Code, Codex, another coding agent, or a human-authored change.

This guide expands the original two-minute review gate. Two minutes can be a useful intake check for a small change. The full review takes the time its scope and risk require. A timer is not evidence that code is correct.

What a reviewer needs before opening the diff

Keep one review packet in the PR body or a file linked from it.

For an uncommitted patch, include its diff and working-tree status and hold that state stable while it is reviewed. A branch name alone can move. If the patch changes after a check, say which evidence needs refreshing.

Download the review-packet template↗, or use the handoff builder for a shorter brief.

A report that still needs evidence

This is a deliberately incomplete, fictional example:

“Fixed retries. Tests pass. Ready to merge.”

The reviewer cannot tell which retry behavior changed, what revision was checked, which tests ran, or who should accept it. Ask for those missing facts before treating the report as a review request.

Here is a more useful illustrative draft. Verification stays pending because no run was performed for this article:

Goal: A timed-out write must not be repeated unless its operation is
      explicitly marked safe to retry.
Acceptance: A non-retryable write takes no second attempt. A retryable
            operation follows the existing maximum-attempt setting.
Change: src/retry.ts and src/retry.test.ts.
Revision: PENDING — add the actual repository, base and head/diff.
Constraints: Keep the public API and default timeout unchanged.
Verification: NOT RUN in this example. Record the real commands,
              outcomes and output links before requesting acceptance.
Open question: Where does the caller declare retry eligibility?
               Confirm that assumption in the current code.
Next owner: Named reviewer — identify missing evidence and checks.
Acceptance owner: Named maintainer — decides after verification.
Work reference: Add the returned Scout reference if this was tracked.

This draft helps prepare the review. It is not ready for acceptance. Keeping a gap visible is more informative than replacing it with a confident summary.

Record what checks prove

Separate a suggested check from a check that ran. For every executed check, retain enough evidence to inspect its result:

Check:
Exact command or manual steps:
Revision / working-tree state:
Environment and relevant version:
Observed result:
Output or artifact link:
Limitations / behavior not covered:

A successful build establishes that the build completed under those conditions. It does not establish that a retry never duplicates a write. A focused test may cover that behavior; a reviewer still needs to inspect whether the test models the requirement. Failed checks and checks not run belong in the packet as well.

Avoid reporting “all tests pass” when only a subset ran. For a manual check, describe the actual input and visible outcome. Redact secrets and customer data before sharing evidence with another person or model provider.

Make the review decision explicit

The first pass asks whether the packet is sufficient to start reviewing. If scope or evidence is missing, return a concrete request for it. Then review the actual change and record an outcome:

Acceptance and release authorization are separate decisions. A packet does not grant permission to merge, deploy, send messages or modify another system. Follow the project's existing approval and release process.

When a fix changes the reviewed code, refresh the diff and relevant checks before closing the finding. Keep the earlier finding linked so the reviewer can see how it was addressed.

Use Scout to carry the request and return path

Scout can route a bounded review to another supported harness and preserve its returned work reference. Include the exact revision, intended behavior and permitted actions. Follow the Claude Code and Codex review workflow for setup, waiting and follow-up commands.

The receipt establishes that a request was recorded; the reviewer still has to return a result. A second agent's findings are evidence for the acceptance owner. An explicit no-findings reply is useful, but does not certify correctness. See delivery, completion and acceptance.

Scout's current scope is high-trust local developer pilots. The reviewer's provider can receive the task data it needs, and another person needs authorized access to referenced files. The architecture explains what the broker owns and observes.

Try the practice on one team's work

Use the same packet for a small run of comparable tasks. Record human time spent reconstructing context, requests for missing evidence, and rework after acceptance. Keep the sample and limitations with the results. This article reports no measured time saving or defect reduction.

For the next change, fill the packet before asking for review. If responsibility will change during the task, add the teammate handoff so the next person can find the current artifact and decision.