Your Agent Writes the PR Description, but It Only Tells You What the Code Does

The description that reads like a code tour

You open a PR from your agent. The description is tidy:

• Added input validation for the /checkout endpoint
• Refactored calculateTax into a separate module
• Updated unit tests to cover the new edge case
• Bumped minor dependencies

It reads clean. It tells you what the diff does. It does not tell you:

• Why validation was added now (was there an incident? a customer ticket? a security finding?)
• What was rejected and why (did you try middleware-level validation first?)
• What the author is unsure about (does the new tax module handle international addresses?)
• What the reviewer should actually look at (is the migration reversible? what happens to stale sessions?)

That second list is the whole reason you ask a human to review. The first list is what git diff --stat already told you.

Reviewers can't reverse-engineer the why

When the description only narrates the diff, the reviewer has two bad options:

1. Approve on vibes. The code looks reasonable, tests pass, ship it.
2. Reverse-engineer the intent by reading the diff carefully, then guess at the edge cases the author was worried about.

Option 1 is how subtle bugs ship. Option 2 turns a 15-minute review into an hour, and the reviewer still has to ask in the comments "why this approach?" — which is exactly what the description should have answered up front.

The agent writes the description from the same diff it just produced. It has no incentive to surface uncertainty, because from its point of view the change is already correct. Listing the things it is unsure about feels like admitting failure, and the prompt it was given asked for a summary, not a risk list.

The prompt that flips it

Stop asking the agent for a summary. Ask it for the parts a reviewer actually needs.

Before you open the PR, write a short section for each of these:

1. What broke or what request made this change necessary — one sentence, not a paragraph.
2. What you tried and abandoned — the approach you started with and why it was worse.
3. What you are still unsure about — the edge case, the migration step, the version bump you are least confident about.
4. What the reviewer should actually check — the one function or behavior you want eyes on, not the whole diff.
5. How you verified it — the exact command and the output, not "tests pass."

The first three are what a senior engineer would say in the PR if they were sitting next to you. The last two are the minimum a reviewer needs to do the job in fifteen minutes instead of an hour.

Why this is easy to skip

It feels like extra process. In practice it is a one-paragraph addition to the same prompt the agent already runs, and it changes the shape of review from "read the diff and guess" to "respond to the concerns the author already raised."

When the agent lists what it is unsure about, the review itself gets better: reviewers stop spending energy hunting for the obvious bug and focus on the actual open question. When it writes the verification command inline, you can run that command instead of taking "tests pass" on faith.

A diff narration is useful as a table of contents. It is not a substitute for the engineering judgment that a review exists to check.

The same gap shows up in API changes

The pattern is the same when the agent touches an API: it documents the new field, lists the new status codes, and leaves out whether the change is backward compatible, what happens to old clients that send the old shape, and whether the spec has been re-checked against the live endpoint. A description that only narrates the contract drift is just as useless as one that narrates a refactor.

We wound up building that last check directly into the local flow in Powerduck — the spec stays the source of truth, and the agent has to re-run it against the live endpoint before it can claim the change is done. The PR still needs a human, but the "did the contract actually move?" question stops being a review-time surprise.

What to change tomorrow

Look at the last three PRs your agent opened. Read the descriptions as a reviewer who has never seen the code. If you cannot answer "why this change, what was rejected, what are you unsure about," the prompt is the problem, not the model.

Stop asking for a summary. Ask for the parts you would say out loud to a teammate sitting next to you.