How to Write a PR Description Reviewers Actually Read

Write a pull request description in the order a reviewer thinks: what changed, why it changed, how to check that it works, and what it breaks. That is how to write a PR description people finish reading. Base the "what" on the diff, not on your memory of the work, and write the "why" yourself, because the diff never contains it. Descriptions that open with implementation detail, or that leave the reviewer to ask what the change is for, are the ones that get skimmed.

The order a reviewer needs

A reviewer opening a PR is building a mental model fast. The order of information either helps that or fights it:

1. What changed. One or two sentences in plain language, not a restated file list.
2. Why. The problem it solves or the reason it is happening. Most descriptions skip this, and it is what a reviewer needs most to judge whether the approach is right.
3. How to verify it. Real commands or the test that proves it works, so review becomes checking a claim instead of only reading code.
4. What breaks. A renamed parameter, a removed export or a changed response shape, stated plainly instead of left for someone downstream to discover.

A template that fits on one screen

• Summary: one or two sentences on what changed.
• Why: the problem or motivation, with the issue linked.
• How to test: the specific steps or test that verify it.
• Risk and rollback: what could go wrong and how to revert.
• Breaking changes: named explicitly, or "None."

Two GitHub details make this stick. Save the template as .github/pull_request_template.md and contributors see it in the body of every new PR, though GitHub's docs note it only takes effect once merged into the default branch. And write Closes #123 in the Why line. GitHub closes the linked issue when the PR merges into the default branch, and ignores the keyword on a PR aimed at any other branch.

Drafting it from the diff

A description written from memory describes what the author meant to do. Somewhere in a long branch, a small change gets made and forgotten, and the description never mentions it. Drafting from the diff ties the "what" to the code that will merge. That is the case for having an AI tool write the first draft.

The same strength is the weakness. The diff shows what the code does and nothing about why. A generated draft that fills in a reason is guessing, and a confident guess reads exactly like the truth. The pack's description writer is told never to describe a change the diff does not contain and never to invent test steps, and it says when steps need a human. That helps with the "what." The "why" still has to come from you.

There is a second cost that no instruction fixes. A clean, plausible summary invites the reviewer to trust the summary instead of the diff. A better description can mean a lighter review. The habit that helps is a reviewer checking one claim in the summary against the code before reading the rest, which turns the description into something tested, not trusted.

What to leave out

• A restated file list. The diff view already shows which files changed. Explain the change instead.
• Narration with no reason. "Changed the loop to use a map" says what but not why. Pair each what with a why, or drop it.
• A copy of the ticket. Link the issue for full context instead of pasting it into the PR body.

Pairs well with

The Technical Documentation Engine ($99) carries the change past the PR into READMEs, API references, ADRs and changelogs, with an auditor that returns DOCUMENTED or GAPS. When the PR changes a data model, the Ontology Change-Impact Tripwire ($79) grades the change as ADDITIVE, BREAKING or SILENT BREAK, which tells you what belongs in the Breaking changes line. For upgrade PRs, the Codex Migration & Refactor Pack ($99) runs a verifier that returns SHIP or HOLD with file-and-line proof.