What should an AI-assisted pull request include so another developer can understand and review it?

TL;DR

An AI-assisted pull request is reviewable when it stands without its author and without the chat that produced it. Write it for a reader who was not there: the problem and intended behaviour, what is deliberately out of scope, the decisions and assumptions behind the approach, the checks that ran on the final commit, what nobody checked, and who answers for it. Then test it: a reviewer who took no part reruns the critical check from the pull request alone, and each question they ask marks a missing line.

Two projects that wrote their expectations down

Some open-source projects have written down their expectations. The Linux kernel's guidance on AI coding assistants says an AI agent must not add a Signed-off-by tag, because only a person can certify the Developer Certificate of Origin. The human submitter reviews all AI-generated code, takes full responsibility, and adds an Assisted-by: tag naming the AI and any specialised analysis tools used (Linux kernel: AI Coding Assistants). LLVM requires a human in the loop: contributors review all generated code or text before asking anyone else to, must be able to answer questions about it, and note substantial tool use in the description or a commit trailer (LLVM AI Tool Use Policy). Unreviewed output, it says, is an extractive contribution: it costs reviewers more than it is worth.

In December 2025 a developer asked in GitHub's community discussions which checks people recommend before merging AI-generated code into main branches. The same month, someone asked on Hacker News how to give feedback on co-workers' mostly AI-generated pull requests. The colleagues disclosed their AI use and said they had reviewed the code, yet the reviewer still could not tell whether they knew what they had submitted, or which parts reflected their own judgement. One reply suggested asking for comments that describe the solution at a higher level of design, with a justification for each choice.

Disclosure alone had not made those changes reviewable; the reasoning was missing.

Write for the reader who was not in the chat

Much of what an agent knew lives in a conversation the reviewer never sees: the first request, the corrections, the approaches it dropped.

Google's guidance on change descriptions names the reader to write for. The body should explain the problem being solved and why this is the best approach, mention any shortcomings, and carry enough context for reviewers and future readers, because a linked resource may later be invisible to them (Google: writing good CL descriptions). A link to a chat transcript is that kind of resource, and even when it opens, it asks the reviewer to rebuild the reasoning from hundreds of turns. The article on what to save for a new AI coding session makes the same point about handing work from one session to the next.

Generated descriptions have a failure of their own. A study of 23,247 pull requests from five coding agents found that about 1.7% had a description clearly at odds with the code, most often claiming changes that were never implemented. Those were accepted far less often and took about three and a half times longer to merge (Gong et al., MSR 2026 Mining Challenge). That is an association, not a cause, and most descriptions were consistent; a generated summary is still a claim about the diff, to be checked like any other.

What the review packet should contain

Treat the pull request as a review packet: everything a reviewer would otherwise have to ask the author, or the chat, for. A one-line fix needs a line per item; a change to shared code, a schema or authentication needs each written out.

Put the structure where people will use it. GitHub fills new pull request bodies from a pull_request_template.md in the repository root, the docs folder or .github (GitHub: pull request templates). An agent can draft it, but the author edits it: the assumptions and the ownership line are what an agent is least able to state about itself.

Tie each claim to a line in the diff

A description says what the change does; the diff is where a reviewer checks it. Make the connection explicit:

• Review your own pull request first. GitHub suggests reading the diff, looking for accidental changes and confirming builds and tests ran (GitHub: helping others review your changes). For an AI-assisted change, also read the description against the diff sentence by sentence and delete any claim you cannot point to.
• Comment where the decisions land. Comment on your own diff at the lines a decision or assumption affects, so the reviewer meets the reason with the code.
• Name tests by behaviour. Next to each intended behaviour, give the test that would fail if it broke. A behaviour with no test belongs under unresolved concerns, not under evidence.
• Record evidence for the final commit. A pass before the last push says nothing about the code under review. The article on verifying that an AI agent actually ran the checks it says passed covers what that record needs.
• Link documentation from the behaviour it describes, and note any left unchanged on purpose.

Reread the description before merging, too; Google's guidance notes that changes can drift a long way during review.

Hand the packet to someone who was not there

Only a stranger can tell you whether the packet works.

This is an editorial method, not a measured practice; nothing cited here shows it reduces defects. It does answer the harder question. If another maintainer cannot reproduce the critical check while the author is still there to ask, they will not manage it after the author has left.

Some tools already separate who asked for a change from who approves it. GitHub's Copilot cloud agent documentation says that when a repository requires approvals, the approval of the person who asked Copilot to create the pull request does not count, and another reviewer must approve (GitHub: review Copilot's output). Its commits list that person as co-author and link to the session logs, so a reviewer can trace why a change was made (GitHub: managing agent sessions). A session log is a useful trail when something needs explaining, but it records what the agent did in order, not what a reviewer needs to decide.

Records that outlast the chat

Paqad produces part of the packet as a by-product of the work. Each code change gets an evidence bundle holding its plan, the frozen specification where the lane requires one, the decisions a person resolved, the recorded review with its rollback plan, and a structured report from the project's own format, test and build commands. A stage marked but with no recorded work is shown as such, never as done. paqad-ai feature report renders the bundle as one HTML page for a reviewer, and paqad-ai deliver can post the receipt on the pull request once CI is green.

The limits matter here. The bundle is local and excluded from version control by default, so a reviewer on another machine sees what was posted or exported, not the folder itself; the committed decision packets are the part that travels with the code. The recorded review is a model's judgement, Safe to merge attests that the gates that ran passed, and a fingerprint shows a file has not changed since it was recorded, not that anyone signed it. None of it writes the problem statement or the ownership line for you. Paqad's workflows overview lists the stages of a change and what each one leaves in its evidence bundle.

Frequently Asked Questions