What to Include When You Ask an Agent for a Pull Request

A pull request description that says "fixes the login bug" and nothing else has a cost, and the cost is paid by whoever reviews it. The reviewer opens the diff, finds forty changed files, guesses at the intent, and reconstructs a story the author already knew. An agent asked to work from that description starts from the same deficit. It reads the diff, infers a purpose, and produces a review that may be technically correct and still miss the point. The description is the only place where the author's intent survives the translation from human thought into code, and most of the time it is treated as a formality.

The interesting question is what an agent actually needs from that description. Not what a human teammate tolerates, but what a machine reads, weighs, and uses to produce a useful review. The two lists overlap, and they are not identical. A human reviewer fills gaps from context, memory, and social knowledge. An agent fills them from the text. What is written down is what gets reviewed.

This is a practical inventory of what belongs in that text, organized around what the agent does with each piece.

The one-sentence claim the change makes

Every pull request asserts something about the world. The login endpoint no longer accepts expired tokens. The export pipeline writes to a temporary file before replacing the target. The settings page stops crashing when the user has no saved preferences. That sentence is the spine of the review. An agent that cannot state it back cannot check whether the diff supports it.

A good claim is falsifiable and narrow. "Improves performance" is neither. "The list endpoint returns results in under 200 ms for accounts with fewer than 10,000 records, down from roughly two seconds" tells the reviewer what to verify, what to question, and what the author measured. The number matters less than the specificity of the assertion. A claim that cannot be wrong cannot be reviewed.

Put this sentence near the top. Not buried under a template heading that says "Description" and then a paragraph of setup. The first thing the agent reads should be the thing the change is trying to do.

The problem before the fix, in concrete terms

A claim without a problem is a solution looking for a justification. The reviewer needs to know what was broken, what was slow, what was confusing, or what was missing. This is the section where vague language does the most damage. "The current implementation has some issues with error handling" gives the agent nothing to work with. "When the payment provider returns a 502, the checkout page shows a blank screen and the order stays in a pending state with no way to retry" gives it a scenario, a symptom, and a consequence.

The concrete version also tells the agent what not to break. If the problem was a blank screen on 502, the reviewer knows to check that the fix preserves the existing behavior for other error codes. If the problem was a slow query, the reviewer knows to check that the new index does not slow down writes. The problem statement doubles as a list of constraints.

One line is enough when the problem is obvious. It rarely is. Two or three sentences that describe the observable symptom, who encounters it, and what happens as a result will do more for review quality than any amount of prose about the elegance of the solution.

What the change does not touch, stated on purpose

Scope is the most common source of review noise. A diff that touches authentication middleware, a logging utility, and a test fixture invites the reviewer to wonder whether the logging change is related, whether the test change hides a regression, and whether the auth change is complete. An agent reading the diff without a scope statement has to guess, and its guesses will be conservative: it will flag the unrelated changes as risks because it cannot tell whether they are intentional.

A sentence that says what is out of scope removes that ambiguity. "This does not change the token format itself, only the validation path. Existing tokens remain valid." "The logging change is a drive-by cleanup, not part of the fix." "No database migration is included; the new column is read but not written in this change." Each of these tells the agent which parts of the diff to treat as the subject and which to treat as context.

The out-of-scope statement also protects the author. A reviewer who knows the migration is coming in a follow-up will not block the current change for not including it. An agent that knows the logging change is incidental will not spend its review budget on it.

How the change was verified, including what was not tested

An agent cannot run the code. It reads the diff and the description and reasons about both. The description is the only place where the author can say what was actually exercised. "Added unit tests for the expired-token path" is useful. "Manually tested against the staging environment with a token expired by 30 seconds and one expired by 30 days" is more useful, because it tells the reviewer which edge cases were considered and which were not.

The negative half of this is equally important. "The concurrent-refresh case is not covered by tests; it was hard to reproduce locally" is a sentence that changes how a reviewer reads the diff. It flags a known gap instead of leaving the agent to discover it and wonder whether the author missed it or deliberately deferred it. Stated gaps get discussed. Unstated gaps get discovered late, usually in production.

This section is where honesty pays. A description that claims full coverage when the tests only cover the happy path teaches the reviewer to distrust the rest of the description. An agent that finds an untested branch after reading a claim of thorough testing will weight every other claim down.

The specific places where a reviewer should look hardest

Authors know where the risk is. They know which function was awkward to write, which assumption is load-bearing, which line they rewrote four times. That knowledge is usually kept private and the reviewer is left to find the soft spots. Pointing at them is not weakness; it is the fastest way to get a useful review.

"The retry logic in processQueue is the part I am least sure about. It assumes the queue is FIFO, which holds today but may not after the planned sharding work." A sentence like that gives the agent a target. It can check the assumption against the surrounding code, look for other places where FIFO is assumed, and flag the coupling. Without it, the agent reviews the whole diff at uniform depth and may never notice the assumption at all.

This is also where an author can preempt a known objection. "I considered using the existing retryWithBackoff helper but it does not support per-item timeouts, so I wrote a local version. If that helper gets timeout support later, this should be consolidated." The reviewer who would have raised that objection now has an answer and can review the actual decision instead of re-litigating the choice.

Dependencies, environment changes, and anything the diff does not show

Some changes live outside the diff. A new environment variable. A dependency bump. A configuration flag that must be set before deploy. A feature toggle that gates the new path. An agent reading only the code will not see these, and a review that misses them is incomplete in a way that matters at deploy time.

A short list is enough: "Requires PAYMENTS_RETRY_LIMIT to be set in production; defaults to 3 if unset." "Bumps requests from 2.28 to 2.31; no API changes used by this code." "Behind the checkout_v2 flag, off by default." Each line tells the reviewer something the diff cannot. The agent can then check that the code handles the unset case, that the dependency bump does not conflict with anything else, and that the flag is actually checked in the right place.

This section is also where rollback belongs, when it is not obvious. "Reverting this change is safe; the new column is nullable and unused by other code." That sentence tells the reviewer the blast radius of a bad deploy. It is the kind of thing that is obvious to the author and invisible to everyone else.

Links to the issue, the design note, and the prior discussion

Context that lives in a ticket, a design doc, or a Slack thread is context the agent does not have unless it is linked. A bare link is better than nothing. A link with a sentence about what to find there is better still. "Design note in docs/checkout-retry.md, section 3 covers the failure modes this change addresses." Now the agent knows where to look and why.

Prior discussion deserves special mention. If a previous attempt at this change was reverted, or if a reviewer raised a concern that was addressed in a follow-up, that history belongs in the description. Otherwise the agent may re-raise a settled objection or miss a constraint that was agreed on elsewhere. A single line, "Previous attempt in #4821 was reverted due to a race in the cleanup path; this version moves cleanup after the commit," saves an entire round of review.

What a reviewer should do with the description once it exists

The description is not a form to fill out. It is a contract between the author and the reviewer about what the review is for. An agent given a description with a clear claim, a concrete problem, a scope statement, a verification note, a risk pointer, and the out-of-diff context can produce a review that engages with the actual change. An agent given "fixes bug" will produce a review of the diff in isolation, which is to say a review of syntax and surface patterns, because that is all it has.

The test for whether a description is good enough is simple: could a competent reviewer who has never seen this codebase read it and know what to check first? If the answer is no, the agent will not know either, and the review will be a generic pass over the diff. The description is the difference between a review that finds the real problem and a review that finds the formatting.

Writing it takes ten minutes. Reading a review that missed the point because the description did not exist takes longer, and the missed problem takes longer still.