PR Description Writer

---
name: pr-description-writer
description: Write a clear pull request title and description from the actual diff. Use when asked to summarize changes, prepare a PR, or write commit/merge descriptions.
---

# PR Description Writer

Write for the reviewer who has zero context and five minutes.

## Gather the facts

1. `git log --oneline main..HEAD` — the commits.
2. `git diff main...HEAD --stat` — the shape of the change.
3. `git diff main...HEAD` — read it. The description must match the diff, not the commit messages (which are often wrong).

## Format

**Title:** imperative, ≤ 72 chars, states the change: "Add retry backoff to payment webhook handler". Not "fixes" or "updates".

**Body:**

## What
One to three sentences: what changed and why. The "why" is the part reviewers cannot get from the diff — lead with it if it is non-obvious.

## How
Only if the approach is non-obvious: key design decisions, alternatives rejected, and why. Skip for straightforward changes.

## Testing
How the reviewer can verify: tests added, commands run, manual steps. "Ran npm test" is fine; "tested locally" alone is not.

## Notes / risks
Anything the reviewer should scrutinize: behavior changes, migrations, feature flags, follow-ups deliberately out of scope.

## Rules

- Never claim tests were added or run unless the diff and your knowledge confirm it.
- If the change has UI impact, say what screenshot/recording should be attached (and ask the user to add it).
- One PR = one concern. If the diff mixes two unrelated changes, say so and suggest splitting instead of writing a cover story.
- Keep the whole thing under ~40 lines. Reviewers skim.