---
name: write-pull-request-description-prompt
description: A prompt that writes a pull request description reviewers can act on fast - a small diagram or tree of what changed, before-and-after evidence such as test output or screenshots, and a merge-danger note on how reversible the change is and what it could affect. Use when the user opens a PR, asks for a PR body, or wants reviewers to understand a change quickly.
license: MIT
metadata:
  category: coding-prompts
  tags: "github,docs,writing"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "pr description, pr body, pull request summary"
  source_url: "https://github.com/mattpocock/skills/tree/a496f5513d4a4cf889bc48e189e579f4b0bdf6aa/skills/engineering/pr"
  source_license: MIT
  copyright: "Copyright (c) 2026 Matt Pocock"
  original_author: "Matt Pocock (mattpocock/skills, pr); inspired by Dex Horthy / Humanlayer (show-me)"
  modified: "Adapted by TheSkillVault: rewrote the PR template guidance as a paste-in prompt with original examples; dropped glossary-file dependency; added steps, adapt notes, secrets check and done-when."
  imported_on: "2026-11-02"
---

# Write a pull request description (prompt)

A good PR body shows the change, proves it works and says how risky it is to merge. This prompt writes that in a few lines.

## When to use
- You are opening a pull request and need a description.
- Reviewers keep asking "what does this do?" or "did you test it?".
- A change is risky and you want the risk stated up front.

## Steps
1. Get the diff: `git diff main...HEAD` (or the PR's "Files changed").
2. Collect evidence: test output, a screenshot or a before-and-after.
3. Paste both into the prompt below.
4. Check the merge-danger section is honest, then paste the result into the PR.

## Prompt
```text
Write a pull request description for the change below. No preamble, keep prose short.

## Summary
Show the change in the smallest useful view: pseudocode for logic, a call tree for control flow, a file tree for structure, or a short diff sketch. Add one or two sentences on why.

## Evidence
- Before: what happened before (failing test, bug output, screenshot).
- After: what happens now (passing test, output, screenshot).

## Merge danger
- Door: one-way (hard to undo: data migrations, public API changes, deletes) or two-way (easy to revert).
- Blast radius: one word (tiny, local, module, app-wide), plus what could break if it is wrong.

DIFF:
{{DIFF}}

EVIDENCE:
{{TEST OUTPUT OR NOTES}}
```

## How to adapt
- Team has a PR template? Paste it and ask the AI to fill it using these rules.
- For a tiny fix, ask for the summary and evidence only.

## Gotchas
- Scan the diff for API keys, tokens and `.env` values before pasting it into any AI tool.
- Do not let the AI invent evidence. If you have no test output, it should say "not tested".

## Portability
Works on GitHub, GitLab or Bitbucket with any chat AI or coding agent. No tool lock-in. For the commit itself, use write-commit-message-prompt.

## Done when
- The description shows what changed, proof it works and the merge risk.
- A reviewer can understand it without opening every file.

## Example prompt
"Write the PR description for my branch. Here is the diff and the test output."

---
Adapted from "pr" in mattpocock/skills (MIT, Copyright (c) 2026 Matt Pocock). The upstream skill credits Dex Horthy / Humanlayer ("show-me") as inspiration. See LICENSE.txt.