Pr Description Writer

PR Description Writer

Write a pull request description a reviewer can act on in 30 seconds — grounded in the real diff, not a guess. A good PR description answers three questions before the reviewer has to ask: What changed? Why? How do I know it's safe?

Preflight — gather the ground truth

Do not write anything until you have read the actual change. Run, in order, and stop degrading gracefully if a command is unavailable:

1. Determine the base branch. Try git symbolic-ref refs/remotes/origin/HEAD → strip to name; fall back to main, then master. If the user named a base, use it.
2. git diff --stat <base>...HEAD — the shape of the change (files, insertions/deletions).
3. git log <base>..HEAD --format='%s%n%b' — the commit narrative (intent lives here).
4. git diff <base>...HEAD — the actual change. For large diffs (>~600 lines), read the full stat, then read the diff of the highest-signal files (source over lockfiles/generated) and sample the rest.
5. If gh is available: check for a repo PR template (.github/pull_request_template.md or .github/PULL_REQUEST_TEMPLATE/). If one exists, fill it out — do not invent your own structure.

Procedure

1. Classify the PR into one primary type: feature / fix / refactor / perf / docs / chore / revert. This sets the emphasis (a fix leads with the bug; a refactor leads with "no behavior change").
2. Find the "why." Look in commit bodies, linked issue numbers (#123, JIRA-456), and code comments touched by the diff. If the why is genuinely unrecoverable from the material, write a > TODO(author): why? line rather than fabricating a rationale.
3. Summarize what changed as an ordered list keyed to reviewer impact, not file order. Group by subsystem. Call out anything a reviewer would otherwise miss: new dependencies, config/env changes, migrations, feature flags, public API/signature changes.
4. Surface risk explicitly. Note backward-incompatible changes, data migrations (reversible?), performance-sensitive paths, and security-relevant edits (auth, input handling, secrets).
5. State how it was verified. Read the diff for added/changed tests and name them. If none exist for non-trivial logic, add a > No tests added — reviewer: is this intentional? note. Never claim testing that isn't in the diff.
6. Link issues using the host's closing keywords (Closes #123) only when the diff plausibly resolves the issue.

Edge cases

• Squash-merge repos: commit messages may be throwaway ("wip", "fix"). Lean on the diff, not the log.
• Monorepo: prefix the title with the affected package/scope (web:, api:).
• Generated/vendored files (lockfiles, dist/, *.pb.go, snapshots): acknowledge in one line ("regenerated lockfile"), don't itemize.
• Revert PRs: state what is being reverted and why, and whether a forward-fix is planned.
• Huge PR: if the diff spans unrelated concerns, say so and suggest splitting — a reviewer-honest description beats a tidy lie.
• Secrets: if the diff appears to add a credential/API key, stop and warn the user prominently instead of describing it.

Quality bar

• Title: <70 chars, imperative mood, scoped. Bad: "Updates". Good: "api: retry failed webhook deliveries with backoff".
• A reviewer who never saw the code knows what to look at first.
• Zero invented facts. Every claim is traceable to the diff or commits.
• No filler ("This PR makes some changes"). No restating the diff line-by-line.
• Risk and testing sections are never silently omitted — if empty, say why.

Output template

## Summary
<1–3 sentences: what this does and why, in plain language>

## Changes
- <change grouped by subsystem, reviewer-impact order>
- <new deps / config / migrations / flags called out here>

## Why
<the motivating problem or goal; link the issue>

## Risk & compatibility
- <breaking changes, migrations, perf/security-sensitive paths — or "None: internal refactor, no behavior change">

## How this was verified
- <tests added/updated by name; manual steps; or an honest gap note>

## Related
Closes #<n>  ·  <links>

Output the description in a fenced block ready to paste. If a repo PR template exists, fill that instead and mention you did.