How do I write a pull request description reviewers can use?

A good pull request description saves the reviewer from reconstructing your thinking. A bad one is the title repeated, or nothing at all. Most people know the difference. They just do not want to write it at the end of a long day.

An assistant can draft it from the diff. It can tell what changed. It cannot tell why you changed it, what you tested or what you were worried about, so the prompt below is built to leave those gaps visible instead of filling them with something plausible.

What you need

• The diff: git diff main...HEAD, with your own base branch. For a very large diff, paste git diff --stat and the files that matter most.
• The reason for the change, in a line, if you know it. A ticket link is fine.
• What tests you ran, or "none yet".

The prompt

Paste this into a new chat and fill in the three bracketed fields.

Write the pull request text from the diff below. Use only what the diff and my notes show.

Why this change (if you know): [reason, ticket link, or "not sure"]
Tests I ran (if any): [or "none yet"]
Diff: [paste here]

Output, ready to paste:
- Title: under 70 characters, imperative.
- Summary: 2 to 4 sentences, what and why. If the reason is not in my notes, write "Why: not stated" instead of guessing.
- Changes: bullets grouped by purpose, naming the files. Separate behaviour changes from refactors, renames, formatting and generated files.
- Risk and review focus: where to look hard and why. Call out breaking changes, migrations, new env vars, dependency changes, auth code touched, deleted code, and logic changed with no tests.
- How it was tested: only what I told you or what the diff shows. Never claim tests passed. If unknown, write "Not stated" and give a suggested test plan.
- Rollout and rollback: only if a migration, flag, config or deploy step is involved.
- Questions a reviewer is likely to ask: up to 5, tied to a specific hunk, with your best answer or "Needs author input".
- Needs your input: the facts you could not get from the diff.

Rules: do not invent a motivation, ticket number, benchmark or test result. Do not describe changes you did not see. Plain short sentences, no hype words, no emojis, no em dashes.

How to check the result

Read the summary against your own memory of the change. If the assistant wrote "Why: not stated", good. That is the prompt working. Add your real reason in your own words.

Check the Changes list against the files. The prompt asks it to separate behaviour changes from refactors, renames and generated files. If a rename is listed as a behaviour change, move it.

Look hard at the section on risk and review focus. It should name auth code, migrations, new environment variables, dependency changes, deleted code and logic changed without tests, when the diff shows them. If you know of a risk the diff does not show, add it. That is the sentence a reviewer will thank you for.

Then go through the likely reviewer questions. Each one is tied to a hunk, with the assistant's best answer or "Needs author input". Answer the ones marked that way before you open the pull request, and the review gets shorter.

The "How it was tested" section should say only what you told it. If it says "Not stated", run the tests, or write what you did.

Limits

• It reads the diff, not the whole codebase. It will not know about the caller you forgot.
• It will not claim tests passed. It suggests a test plan if you gave none.
• It cannot judge whether the change is a good idea.
• A huge diff gives a vague description. Splitting the change is the better fix.

Browse all skills in the catalog

Want this as a ready-made skill? PR Description and Review Prep (Free) does it in your own assistant.