Write a pull request description
Turn your change notes into the PR description reviewers actually want: what changed, why now, how it's tested, and what to look at hardest.
Last updated
Fill in the blanks
Assembled in your browser — nothing you type is stored or sent anywhere.
Your prompt
Model-agnostic — works in Claude, ChatGPT, Gemini or any AI chat.
Why this prompt works
- →"Why" before "what" mirrors how reviewers read — a diff they can see; the reason for it they can't.
- →The never-claim-untested-things rule matters specifically here: a generated "all tests pass" line in a PR is a small lie with a long audit trail.
- →Asking for the not-done list turns scope cuts from surprises-in-review into decisions-on-record.
Part by part
- a one-line summary a changelog could reuse
- Forces the change to be describable in user-facing terms, which is a useful test of whether it has a coherent purpose.
- **Why** (the problem, and why now)
- The section a reviewer cannot reconstruct from the diff. The code says what changed; only you know what prompted it.
- grouped by area, not file-by-file
- A file list is already in the diff. Grouping by area is the interpretation that makes a large change reviewable.
- never claim tests I didn't mention
- The honesty constraint that matters most here. An invented testing claim is read as verified by every reviewer.
- anything I chose NOT to do, with the reason
- Pre-empts the obvious review question and shows the alternative was considered rather than missed.
Common mistakes
Write a PR description for these changes.Produces a restatement of the diff, which the reviewer already has. The why and the risk — the parts only you know — are absent because they were not asked for.
Letting it describe the testing.It will write something plausible about unit tests and manual verification. Reviewers read that as a claim, and approve on the strength of testing that may not exist.
Making it sound impressive.A reviewer is deciding whether to approve, not whether to be impressed. Marketing tone in a pull request makes the risky part harder to find, which is the opposite of what the description is for.
Questions
Why does the why section matter most?
Because it is the only part not recoverable from the code. A reviewer can see what changed; whether it was the right change depends on a problem statement only the author has.
What belongs in review notes?
The part you are least sure about, and anything you deliberately did not do. Both direct attention where it is useful, and the second saves a round trip on the obvious suggestion.
Why cap it at 250 words?
Because a description longer than the diff does not get read. If it genuinely needs more, that usually means the pull request should be split rather than explained at greater length.
Should the summary line match the commit message?
Ideally yes, and both should be usable in a changelog. Squash-merging makes the pull request title the commit message, so writing it as one saves rewriting it later.