PR Description Writer

Reviewers decide how carefully to read a change within the first ten seconds of seeing its description. This skill writes merge-request descriptions that buy the change a careful review: what problem it solves, how it solves it, what it deliberately does not do, and exactly how the reviewer can convince themselves it works. It is written from the branch diff, not from the author's optimism.

When to use this skill

• Opening a merge or pull request on any version control host
• Rewriting a description that currently says "misc fixes" or just restates the branch name
• Preparing a risky change (migration, major dependency bump, auth change) for review
• Producing a handover summary when a branch changes owners mid-flight

Workflow

1. Diff the branch against its merge target and read the whole thing. Note anything you would not understand without asking the author — those questions are the outline of the description.
2. Open with the problem in one or two sentences a teammate outside the change can follow. State the user-visible or operator-visible symptom, not the implementation gap.
3. Summarize the approach in a short paragraph: the shape of the solution and the one or two decisions a reviewer might challenge. Name the alternative you rejected and why — this preempts the longest review thread before it starts.
4. List what changed at the level of behaviors, not files; the diff already lists files. Group as: behavior changes, refactors that change nothing, and mechanical noise (generated files, lockfiles, formatting), so reviewers know where to spend attention.
5. Write the verification section: the commands you ran, what you observed, and one concrete script the reviewer can follow in under five minutes to see it working. If some path is untested, say so in plain words rather than letting silence imply coverage.
6. Declare the blast radius: rollout or rollback steps, flags involved, schema or config changes, anything a deployer must know. Write "none" explicitly where that is true.
7. End with open questions for the reviewer, if any. A description with a genuine question gets a more engaged review than one pretending to certainty.

Output format

## Problem
<symptom and why it matters, 1-2 sentences>

## Approach
<solution shape + the decision most likely to be challenged, with the rejected alternative>

## Changes
- <behavior change>
- <behavior change>
- Refactor only: <...>
- Noise: <lockfile, formatting>

## How I verified it
<commands run and observed results; a five-minute reviewer script>

## Rollout / risk
<flags, migrations, rollback plan — or "none">

## Open questions
<or omit the section>

Quality bar

• A reviewer who reads only the description can predict what they will see in the diff; a surprise in the diff means the description failed.
• Never claim "tested" without saying how. "Ran the new unit tests plus a manual pass through the signup flow" is the minimum acceptable specificity.
• The verification script must be copy-pasteable: real commands, real paths, no placeholders left unfilled.
• Length follows risk: a migration deserves every section, a ten-line fix deserves five lines of description. Matching effort to risk is part of the craft.
• No section headers left standing over empty space — delete what does not apply.