Hand off an AI-assisted pull request with reproducible evidence

Describe the problem rather than the prompt

“The AI fixed search” does not tell a reviewer what to inspect. Describe the input, screen or API and incorrect outcome, then identify the basis for expected behavior. If the scope changed during implementation, rewrite the description around the final problem instead of pasting the original request. Prefer concise reproduction conditions to a long transcript. The handoff should let someone who was absent from the conversation establish whether the defect exists and whether the proposed change addresses the same issue.

Explain the diff by purpose

Explain changed files through their behavioral role: validation, rendering, persistence or configuration. If unrelated formatting or dependency changes are mixed in, justify them or separate independent work where practical. For generated files, record the input and reproducible generation step. A small visible diff is not automatically low impact, especially in shared code or configuration. Identify the callers affected by the change so a reviewer can choose relevant checks without reverse engineering every assumption from the file list alone.

Verify the same case before and after

Use the same relevant conditions to demonstrate the defect before the fix and expected behavior afterward. Record commands, environment and tested revision when presenting results. Writing a test is different from executing it successfully. A passing type check does not establish that persistence or an external integration works. State unverified boundaries with a specific reason and next step. This lets reviewers assess the practical limit of the evidence, instead of interpreting an undifferentiated “tests passed” label as complete end-to-end verification.

Show the interaction when UI changes

For a UI change, demonstrate the affected interaction rather than only the initial screen: input, submission, result and recovery when relevant. Include narrow layouts or long labels if the change concerns them. Use shareable synthetic records and exclude personal information or credentials from images. A focused example with clear conditions is more useful than many unrelated screenshots. The evidence should show what changed for the user and the practical conditions under which it was checked, without pretending that one successful screenshot covers every supported browser.

Check the implementation behind the explanation

Check generated summaries against the actual diff and observed results. Remove nonexistent test names, commands that were never run and performance improvements that were not measured. Describe the implemented behavior rather than forcing the initial plan onto a different final patch. When uncertain, return to code or execution evidence instead of merely replacing a confident adjective with a softer one. The review package is accountable evidence about a real revision, and should not inherit unsupported claims simply because an assistant produced a fluent summary.

Record residual risk and recovery

For changes involving deployment settings, stored data or external APIs, explain what recovery would require. Reverting code may not reverse a data change, so distinguish those paths. Even a bounded fix can have unverified conditions that matter to the release owner. A concrete statement of scope and evidence limits is more useful than an unsupported conclusion that there is no risk. Keep the recovery explanation proportional to the change; it should support an actual release decision rather than become a generic checklist copied into every small pull request.

Test the handoff with a fresh reader

Ask whether a fresh maintainer can reproduce the issue, understand the rationale and execute the checks from the pull request alone. For a hypothetical search fix, provide records with and without an optional department, expected results and the relevant commands. Add missing information surfaced by the reviewer to the description or maintenance notes. Review approval, merge and deployment are separate operations; report which actually occurred. A request for review should never be described as a completed production release, however successful the local patch appears.

• Triage AI code-review findings: impact, evidence and acceptance
• Generating unit tests with AI: expected behavior and boundary cases
• Keeping code and documentation aligned during AI development