Pr Describer

pr-describer

Produce a pull request description that a reviewer will actually thank you for. Reads the diff, not the commit messages — commit messages record how you built the change, PR descriptions explain why and what it means for the codebase and its users.

When to use this

• "Write a PR description"
• "Describe this PR"
• "Help me open a PR"
• Just before git push / gh pr create, when the user needs the body

Procedure

1. Determine the diff range

Priority order:

1. If the user specified a base/head, use it.
2. Try git merge-base main HEAD (or master, or the repo's default branch — check git symbolic-ref refs/remotes/origin/HEAD or fall back to main).
3. Otherwise use HEAD~N for a reasonable N if the branch is short.

Get the actual data:

git diff <base>...HEAD --stat
git diff <base>...HEAD
git log <base>..HEAD --no-merges --pretty=format:"%h %s%n%b%n---"

The <base>...HEAD form (three dots) shows the diff from the merge base, which is what a reviewer sees. Do not use <base>..HEAD (two dots) for the diff — that includes any unrelated changes on main.

2. Read the diff, not the commit history

The commit messages describe the process of making the change. The PR description should describe the outcome. Read the actual diff:

• What files were touched, and what's the shape of the change (new file, big rewrite, small edit, config change)?
• What's the user-visible or API-visible impact?
• Are there any migration steps a consumer would need to take?
• Any generated files (lockfiles, snapshots, protobuf) that reviewers should skip?

3. Write the description

Use this structure (adjust for repo conventions if present in .github/PULL_REQUEST_TEMPLATE.md):

## Summary

<1-3 sentences. What this PR does, in plain language. If the reader stops
reading after this section, they still know what merged.>

## Why

<Motivation. Optional if obvious from summary. Link to the issue if there is one.>

## What changed

- **<Area 1>** — what was actually done and why in that area
- **<Area 2>** — same
- <keep this bulleted and short; the diff is one click away>

## Testing

<How was this verified? "Ran the test suite" is fine when true. "Manually
walked through X flow" is fine when true. Be honest — reviewers can tell
when this section was skipped.>

## Screenshots

<Only if UI changes. Before / after. Skip section entirely if not applicable.>

## Breaking changes

<Only if there ARE breaking changes. Be very concrete: exactly what breaks,
exactly what a consumer has to do. Skip section entirely otherwise.>

## Notes for reviewer

<Anything that would save the reviewer time. "The change in `foo.rs` is
mechanical, only `bar.rs` matters." Or: "Ignore lockfile diff." Skip if
nothing to add.>

4. Detect and flag important situations

Scan the diff for these and add appropriate mentions:

• Public API changes (exported functions/types/routes) → mention in "What changed" and consider whether it's a breaking change
• New dependencies added → mention in "What changed"; consider whether the license and size are worth flagging
• Migration files / schema changes → mention explicitly with runbook
• Deleted files / removed exports → breaking change if public
• Secrets, tokens, or .env-shaped strings in the diff → HALT. Do not write the PR. Tell the user something looks like a secret leak and point at the specific lines.
• Commented-out code left in → mention as review note ("Leftover from debugging in X, safe to remove")
• TODO/FIXME added → mention, ask if intentional

5. Length calibration

The right length is proportional to the diff, not to how proud you are.

• ~10 lines changed → summary + testing, maybe one bullet in "What changed". That's it.
• ~100 lines changed → the full structure above, but keep each section tight.
• ~1000+ lines changed → the full structure plus a "How to review" section suggesting an order to look at files.

If the diff is over ~2000 lines and there's no clear reason (generated files, mechanical refactor), offer to the user that this should probably be split into multiple PRs. Then still write the description if they say to proceed.

Anti-patterns

• Do not just paraphrase the commit messages. Read the diff.
• Do not include the diff itself in the description — reviewers see it below.
• Do not use marketing language ("major overhaul", "significant improvements"). Boring is professional.
• Do not skip the "Testing" section. If nothing was tested, say so — that's useful information for the reviewer, not a shame to hide.
• Do not run git push or gh pr create yourself. Hand the description to the user; they push.