The Evidence Package Behind a Strong Coding-Agent Handoff

A coding agent can produce a patch faster than a reviewer can reconstruct why it is safe.

That is not because the reviewer is slow. It is because a diff is an incomplete handoff.

A diff tells you what lines changed. It does not reliably tell you:

• which user problem the patch is intended to solve,
• what behavior must remain unchanged,
• what tests or checks were run,
• whether the agent encountered uncertainty,
• which files deserve the reviewer’s closest attention,
• what would make the change unsafe to merge.

Human code review needs context. GitHub’s pull-request review workflow starts from the pull-request summary and related discussion, then moves through the changed files, comments, suggestions, and approval decisions. Coding-agent changes can make that context more important because a reviewer may encounter a broad surface area without having watched the implementation develop.

A patch is implementation evidence. A handoff is the package of evidence that lets another person decide whether the patch should advance.

The quality bar for an agent should therefore include the clarity of its review package, not only whether it produced code.

A proposed five-part change evidence package

Virillio Code Editorial proposes that an agent-authored change arrive with five concise artifacts. This is an editorial handoff model, not a universal code-review standard; teams should adapt it to their risk, repository, and approval process.

• Artifact: Intent — Question it answers: What user or system problem is this solving? — What a reviewer needs: A plain-language goal and acceptance criteria
• Artifact: Change map — Question it answers: Where and how did the implementation change? — What a reviewer needs: A route through the diff, public surfaces, and dependencies
• Artifact: Verification — Question it answers: What evidence supports correctness? — What a reviewer needs: Commands, targeted tests, outcomes, and known gaps
• Artifact: Residual risk — Question it answers: What remains uncertain or intentionally out of scope? — What a reviewer needs: Assumptions, tradeoffs, migrations, rollback considerations
• Artifact: Review route — Question it answers: Where should a human begin? — What a reviewer needs: The highest-leverage files, decisions, and questions

This is deliberately smaller than a transcript. A reviewer does not need every model thought or shell line. They need the structured facts that make a merge decision accountable.

1. Intent: write the contract before the summary

An agent should begin the handoff with the user-level objective, not a list of changed files.

Weak:

“Updated pagination implementation.”

Useful:

“Fix continuation requests so they preserve the initial filter and ordering. Existing cursors remain opaque, and the wire response shape does not change.”

The second version gives a reviewer something to test against. It names the desired behavior and the constraints that define a correct implementation.

Include:

• the motivating issue, request, or incident;
• success criteria stated in user or API behavior;
• constraints that must not regress;
• explicit non-goals.

The intent section should be short enough to read before opening the diff. If it needs several pages, the task may need decomposition before review.

2. Change map: orient the reviewer through the surface area

Large diffs are not inherently bad. Unmapped diffs are.

The change map tells a reviewer where the conceptual boundaries are:

• Map field: Public surface — Example: One client method gains a cursor continuation argument
• Map field: Domain rule — Example: Continuation inputs use the stored initial filter instead of a new filter
• Map field: Implementation area — Example: Request parser, service layer, and generated client projection
• Map field: Compatibility boundary — Example: Existing response envelope and error class remain unchanged
• Map field: Tests — Example: Regression test for filtered continuation and generated-client behavior

The map should mention important files and symbols, but it should not reproduce the entire file list. Its job is to turn a flat diff into a review plan.

For an agent, this is also a scope check. If the change map cannot explain why a file changed, the agent should either remove the change or flag it as incidental risk.

3. Verification: show evidence, not confidence

“Tests pass” is a conclusion, not evidence.

An agent handoff should state:

• which targeted checks it ran,
• whether the starting state reproduced the issue,
• what outcome changed after the patch,
• which broader checks passed or were not run,
• whether any result is flaky, partial, or environment-dependent.

Use a compact structure:

• Check: Targeted regression — Result: Passed — What it establishes: The reported filter-loss case now preserves continuation semantics
• Check: Type or schema check — Result: Passed — What it establishes: Public request and response types remain internally consistent
• Check: Full suite — Result: Not run — What it establishes: Excluded because the change was time-bounded; reviewer should decide whether it is required

This is not about making the agent look cautious. It is about making the uncertainty actionable. A review may accept a narrow verification record for a small internal refactor and require a larger one for a public API change. The handoff gives the human the information needed to make that call.

4. Residual risk: preserve uncertainty instead of hiding it

Agents are good at producing plausible explanations. That makes explicit uncertainty essential.

Residual risk covers facts such as:

• a migration path was not exercised,
• an integration test requires credentials or a separate environment,
• a retry path remains untested,
• a public naming choice needs product confirmation,
• a generated artifact was deliberately not changed,
• a broader refactor was identified but excluded from scope.

For each item, state the reason and the proposed next action:

• Risk or uncertainty: No staging integration run — Why it remains: Environment was unavailable — Suggested disposition: Run the scoped staging scenario before merge
• Risk or uncertainty: Rename alternatives remain — Why it remains: Product namespace is not settled — Suggested disposition: Hold public API rename for design decision
• Risk or uncertainty: A wider cleanup is possible — Why it remains: Outside the requested fix — Suggested disposition: Track separately; do not bundle into this change

The important behavior is not “list every imaginable risk.” It is “do not turn missing evidence into an implied pass.”

5. Review route: invite the human to apply judgment

A good agent handoff does not ask the reviewer to rubber-stamp a summary. It highlights where human judgment matters most.

The review route should say:

• which one or two decisions deserve a close read;
• where a public or irreversible contract changed;
• which tests best demonstrate the intended behavior;
• what questions the agent could not resolve from the available context.

For example:

“Start with the continuation-token ownership rule in the service layer. Then review the regression test that proves an initial filter cannot be swapped on a later page. The remaining decision is whether the client should expose the opaque cursor under the existing plural namespace or a future singular namespace.”

This is how a handoff turns an agent’s speed into a reviewer’s leverage.

A filled example: a filtered-pagination regression

Suppose an issue reports that requesting the next page drops an initial status=open filter. An illustrative, fully populated evidence package could look like this:

• Artifact: Intent — Filled entry: Preserve the initial status filter and ordering across continuation requests. Keep the cursor opaque and do not change the response envelope.
• Artifact: Change map — Filled entry: Update the continuation-token ownership rule in src/pagination/service.ts; add the regression case in test/pagination.test.ts; leave the public schema and generated client untouched.
• Artifact: Verification — Filled entry: Confirm the targeted test fails on the original snapshot and passes after the patch; run bun test test/pagination.test.ts and the package’s bun typecheck; record that the full repository suite was not run.
• Artifact: Residual risk — Filled entry: The test covers the local cursor store but not distributed-store failover. Run the scoped integration scenario before merge if that deployment path is affected.
• Artifact: Review route — Filled entry: Start with the service rule that binds the cursor to the initial filter, then inspect the regression test. Confirm that no public wire shape or error class changed.

The example is useful because every completion claim has a corresponding check or an explicit gap. A reviewer can disagree with the scope without first reconstructing it from the diff.

Why templates still matter

GitHub documents pull-request templates as a way to provide consistent context. The template is valuable for agents too, but it should not become a form filled with generic prose.

Use fields that force evidence:

• Field: Intent — Required content: User-level goal, acceptance criteria, non-goals
• Field: Change map — Required content: Public surface, behavior rule, implementation areas
• Field: Verification — Required content: Checks, results, and any unrun required check
• Field: Residual risk — Required content: Assumptions, unresolved evidence, and next action
• Field: Review route — Required content: Highest-leverage files and questions

The fields are small enough to be automatic and specific enough to reveal when the agent does not actually know the answer.

Avoid vague template responses:

• “This fixes the issue.”
• “Tests were run.”
• “No risks.”
• “Please review.”

Those statements consume reviewer attention without reducing uncertainty.

Separate the work record from the reviewer package

Long-running agent systems may retain a rich operational record: tool output, build logs, partial attempts, screenshots, and intermediate artifacts. That can be useful for debugging, audit, or further agent work.

It is not the same as the reviewer package.

The reviewer package should point to deeper evidence when needed, while keeping the main handoff bounded. A reviewer should be able to understand the intended change from that package, then drill into logs or artifacts only where the risk warrants it.

This separation protects both attention and provenance:

• the operational record preserves what happened;
• the review package explains why the change is ready—or not ready—to advance.

Design handoffs for interruption and resumption

Anthropic’s application-development harness and its earlier long-running-agent harness guidance describe structured files and incremental state that carry work between sessions. Treat human review as another kind of session boundary.

If an agent returns later to address feedback, it should not reopen the task as if it were new. It should receive:

• the original intent and constraints,
• the change map,
• review comments and their status,
• the previous verification record,
• the new requested decision or correction,
• any changed environment or policy.

This makes review feedback a durable input to the workflow, not an unstructured conversation fragment.

Measure handoff quality

You can evaluate this workflow without grading prose style:

• Review time to first useful comment: Did the package help a reviewer find the important question faster?
• Evidence coverage: Did every material claim map to a test, artifact, or explicit uncertainty?
• Scope surprises: Did reviewers find changed surfaces absent from the change map?
• False-completion rate: How often did “tests pass” conceal an unrun or failing relevant check?
• Feedback resumption quality: Could a later agent iteration address comments without reopening unrelated work?

These measures make the handoff a product surface that improves over time.

What we are learning building Virillio Code

The in-development work at Virillio Code supports a simple principle: a durable handoff should carry the smallest structured evidence package that lets the next actor make a sound decision. For code review, that actor is often a human with context, standards, and judgment the agent does not possess.

A strong coding agent does not just produce a diff. It makes the diff reviewable.

Sources and further reading

• Harness design for long-running application development — Structured artifacts help people and later sessions carry progress through long-running coding work.
• Effective harnesses for long-running agents — Incremental work and explicit artifacts can make later agent sessions more productive.
• Quickstart for reviewing pull requests — Pull-request review depends on context, changed files, comments, suggestions, and review decisions.
• Managing and standardizing pull requests — Pull-request templates provide consistent context needed by reviewers.

Editorial disclosure

This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.