PR Description Generator

Why the PR description is the highest-leverage thing you write

A pull request description is read far more often than the code inside it. Reviewers use it to decide where to focus, future maintainers use it to reconstruct why a change happened, and increasingly an AI reviewer uses it as the ground truth for what the diff was supposed to do. A vague description turns every review into an interrogation - the reviewer has to reverse-engineer intent from the diff before they can judge it. A tight description does the opposite: it front-loads the intent, so review becomes a fast yes-or-no on whether the code matches the stated goal.

This generator asks for the seven fields that a good PR body always contains - title, summary, changes, test plan, screenshots note, breaking changes, and linked issues - and emits clean Markdown with proper headings and a real checklist. It is not magic. It is a forcing function that stops you from opening a PR with a one-line title and an empty body.

The anatomy of a PR description reviewers actually read

• Title - one line, imperative mood, describes the outcome not the mechanism. 'Add rate limiting to the API proxy' beats 'changes to proxy.ts'.
• Summary - two or three sentences on what changed and, more importantly, why. The why is the part no diff can ever tell you.
• Changes - a bulleted list of the meaningful edits, so a reviewer can map each bullet to a hunk in the diff.
• Test plan - how you verified it, as checkboxes. This is the single field most PRs skip and the one reviewers trust the most.
• Screenshots or demo - required for anything with a visible surface; a note like 'backend only' when there is nothing to show.
• Breaking changes - stated explicitly, even if the answer is 'none'. Silence here is where production incidents are born.
• Linked issues - so the PR closes the loop and the tracker stays honest.

Write the summary before you write the code

The best time to draft a PR description is before you start, not after. If you cannot write a clean two-sentence summary of what you are about to do, you do not yet understand the change well enough to make it. Teams that write the description first ship smaller, more focused PRs, because the act of describing the change exposes scope creep early. Draft the summary, list the changes you expect to make, then let the diff conform to the plan rather than the other way around.

Keep PRs small so the description stays honest

A description can only be as clear as the change it describes. A 2,000-line PR that touches nine unrelated things cannot have a clean summary, because there is no single thing it does. The strongest signal that a PR is too big is that its summary needs the word 'and' three times. When that happens, split it. Small PRs review faster, revert cleaner, and produce descriptions that a reviewer can hold in their head at once.

Feeding your PR description to Claude Code

Claude Code can both write and review PR descriptions, and the two workflows reinforce each other. To have it draft one, give it the diff and ask for a description in this exact structure - the model is strongest when it fills a known template rather than inventing a format. To have it review a PR, paste the description as the spec and the diff as the artifact, then ask a single sharp question: 'Does this diff do everything the description claims, and nothing it does not?' That framing turns the description into a testable contract, which is exactly what a good review checks.

1. Draft the summary and change list yourself, in your own words - you know the intent better than any tool.
2. Ask Claude Code to expand the test plan by looking at the diff: 'What did I change that this test plan does not cover?'
3. Have it flag hidden breaking changes: 'Does anything here change a public signature, a schema, or an env contract?'
4. Use the emitted Markdown as the PR body, then paste the whole thing back with the diff for a final self-review pass.

Common mistakes this tool prevents

• Empty bodies - the classic 'title only' PR that forces the reviewer to read every line to guess intent.
• No test plan - the reviewer has no idea whether you ran anything, so they either re-test everything or rubber-stamp.
• Silent breaking changes - a renamed field or changed default buried in the diff with no callout.
• Orphan PRs - work that never links back to the issue that requested it, leaving the tracker permanently out of date.
• Wall-of-text summaries - three paragraphs where three bullets would do. Reviewers skim; structure respects that.