PR Descriptions That Get Read (and Merged)

TL;DR: Microsoft's research found the reviewer's central challenge isn't finding bugs; it's understanding the change. The description is the one place the author can pay that cost down in advance, and most descriptions don't even try. Write four things - why, what (at intent level), where the risk lives, how you verified it - and your PR gets picked up faster, read deeper, and merged in fewer round trips. Template below; steal it.

Somewhere in your review queue right now sits a 400-line PR whose entire description reads "fixes bug." The reviewer who opens it must reverse-engineer the problem, the intent, and the risk from raw diff, or do the economical thing: skim it, stamp it, move on. Both outcomes are expensive, and both were purchased by an empty text box. The description is the highest-leverage two hundred words in your delivery pipeline. Here's what goes in them.

Why do PR descriptions matter this much?

Because understanding, not critique, is the bottleneck. When Microsoft researchers studied modern code review, the key challenge reviewers reported wasn't spotting defects; it was understanding the code under review in the first place. Every minute your reviewer spends reconstructing what problem is this solving and why this way is a minute bought by a description that didn't say.

A diff shows what changed. It is structurally incapable of showing why: why now, why this approach, why not the obvious alternative you already tried and discarded. That context lives in exactly one head until the description writes it down. Skip it, and one of two things happens. The reviewer asks, adding a full round trip to your review time. Or the reviewer doesn't ask, and you get a rubber-stamp approval on code nobody actually understood.

There's a speed receipt here too. Reviews move fast when they're easy to start: at Google, small changes get first feedback in under an hour. A clear description is the other half of "easy to start" - the difference between a PR a reviewer can open in a ten-minute gap and one that demands an archaeology session they'll postpone until Thursday. Descriptions are pickup time infrastructure.

What goes in a pull request description?

Four sections, none of them long.

1. Why. The problem, in one or two sentences, plus the ticket link. Not "implements BF-482"; the reviewer shouldn't need to leave the page to learn that checkout double-charges when the retry fires twice.
2. What, at intent level. The shape of the solution: "moved the idempotency check ahead of the charge call; the retry path now short-circuits." The file list is the diff's job. Yours is the sentence the diff can't say. If you rejected an obvious alternative, add one line on why. That line pre-empts the longest thread on the PR.
3. Where the risk is. The bravest and most valuable section: "the tricky part is the lock ordering in session.ts - read that hardest." You know where you're least confident. Pointing the reviewer there converts their scarce attention into inspection where it counts. This steers toward the 70-90% defect-find rate that well-run review achieves instead of spending reviewer energy evenly across boilerplate.
4. How you verified it. Tests added, commands run, screenshots for anything visual, the manual steps you walked. "How was this tested?" is the most common review question there is; answer it before it's asked.

The template, ready to paste into your PR body or .github/PULL_REQUEST_TEMPLATE.md:

## Why
<problem + ticket link>

## What
<the approach, 2-4 sentences; alternatives rejected, if any>

## Risk / read this hardest
<the part you're least sure about>

## Verified
<tests, commands, screenshots, manual steps>

Four ways descriptions fail

The failure modes are symmetrical:

• The empty box. Outsources understanding to the reviewer at the worst exchange rate available. One author-minute of writing saves five reviewer-minutes of reconstruction. Declining that trade on every PR is a system-wide tax.
• The essay. A description that needs a table of contents is describing a PR that needs splitting. The fix isn't better prose; it's a smaller PR. Cisco's data caps effective review at 200-400 lines at a time, and no description rescues a diff past the limit of what a human can hold.
• The diff transcript. "Changed parseUser, updated three tests, bumped the fixture." The reviewer has the diff open; narrating it adds words without adding understanding. Every sentence should carry something the code can't.
• The stale description. Push a rewrite after review round two, leave the description describing round one, and it now actively misleads. The description is part of the change; update it when the change changes.

Making it a habit instead of a rule

Make it structural, then make it cultural. Structural: the repo-level PR template above, so the four headings greet every author. A blank under "Risk" asks the question so a human doesn't have to. Cultural: reviewers treat a missing description the way they'd treat missing tests. "Happy to review this; can you fill in the why and the risk section first?" is a completely fair first comment, and on a healthy team it reads as process, not friction.

Authors on tiny teams get the biggest payoff, incidentally. When your one reviewer is also your one other engineer, every minute of their attention you save is a minute your team gets back, and when there's no reviewer, the description becomes the record your future self reads. It's the same skill everywhere: the PR description is feedback you give in advance - to your reviewer, your future self, and the person who git-blames this change in two years.

The door: add the four-heading template to your repo today, and write the "risk" section honestly on your very next PR. Watch what happens to the first review comment you get back - it will be about the thing you flagged, which means, possibly for the first time this quarter, the review went exactly where you needed it.