Pull Request Description Writer

Turn a diff into a PR description that explains why the change exists, what a reviewer should scrutinise, and how it was tested.

The Prompt — replace [BRACKETS] with your details

Act as a thoughtful engineer writing a pull request description for reviewers who have not been in your head.

The change:
```diff
[PASTE THE DIFF, OR A SUMMARY OF THE FILES AND WHAT CHANGED IN EACH]
```

Context:
- The problem this solves: [ISSUE, BUG REPORT, OR REQUIREMENT]
- Approach I chose and one I rejected: [IF ANY]
- How I tested it: [MANUAL STEPS, TESTS ADDED, ENVIRONMENTS]
- Risk: [WHAT COULD BREAK, WHAT IS BEHIND A FLAG]
- Related work: [LINKED ISSUES, FOLLOW-UP PRS]

Write the description with:
1. A title under 70 characters in the imperative mood
2. Why this change exists, in two or three sentences, understandable to someone who has not read the issue
3. What changed, grouped by intent rather than by file — separate the functional change from the incidental refactor
4. Where a reviewer should look hardest, and the specific question you want answered at each spot
5. How to verify it locally: exact commands or steps
6. Risk and rollback: what happens if this is wrong, and how to undo it
7. What is deliberately out of scope, with a link or note for the follow-up
8. A checklist of anything that needs to happen at deploy time: migrations, config, feature flags, backfills

Rules: describe only what is in the diff. If something in the diff is unexplained by my context, ask me about it rather than inventing a rationale.

How to use this prompt

Include the rejected approach — it is the part reviewers most often ask about and the part descriptions most often omit.
Section 4 is the highest-value part: pointing reviewers at your own uncertainty gets you better review.
If the model asks a question about the diff, answer it in the PR. Someone else would have asked it later.

Why this prompt works

A diff shows what changed; only the author knows why, and that is the information a reviewer is missing. Structuring the description around intent, reviewer attention, and rollback turns it into a tool for the reviewer instead of a summary they can already read from the files.

Variations to try

Ask for a shorter version for a two-line fix — a full template on a typo PR is noise.
Add your repository's PR template and ask it to fill in those exact headings.
Ask it to draft the follow-up issue for anything you marked out of scope.

Common mistakes to avoid

Letting the model restate the diff file by file, which tells a reviewer nothing they cannot see.
Accepting an invented rationale for a change you made for a different reason.
Omitting deploy steps, so a migration is discovered in production.

Works well with

Claude

ChatGPT

Gemini

Cursor

Need a custom version of this prompt?

The free prompt generator builds a prompt tailored to your exact goal, framework, and target AI model — or paste this template into the optimizer to refine it.

→ Open the Prompt Generator → Prompt Optimizer

Related prompts

Code Review Assistant

Paste code and get a structured review covering bugs, readability, performance, and securi…

Debug Any Error Message

Paste an error message and the related code to get the likely root cause, a fix, and how t…

Unit Test Generator

Generate thorough unit tests for any function, covering happy paths, edge cases, and failu…

Code Documentation Writer

Generate clear docstrings, inline comments where needed, and a README-style usage section …