Write a clear, structured pull request description

PR Description Writer Skill

Writes structured, reviewer-friendly pull request descriptions from a diff, commit list, or informal notes. Covers the what, why, and how-to-review so reviewers can start immediately.

Required Inputs

Ask for these if not provided:

• What changed (paste a git diff, git log --oneline, or describe the changes in plain English)
• Why it was changed (the problem being solved or feature being added)
• How to test it (any specific steps a reviewer needs to verify it works)
• Risk level (low / medium / high — affects how much reviewer guidance to include)
• PR type (feature / bug fix / refactor / dependency upgrade / config change / hotfix)
• Target branch (e.g. main / develop / release/2.4 — affects risk framing and reviewer guidance)
• Linked issue or ticket (e.g. JIRA-1234, GitHub #567 — or "none")

Output Format

Title

A clear, imperative-mood title under 72 characters: [type]: [concise description of what changed]

Examples:

• feat: add rate limiting to the public API
• fix: resolve race condition in session expiry
• refactor: extract payment logic into PaymentService

Summary

2–3 sentences covering:

• What this PR does (the change)
• Why it was needed (the problem or goal)
• The approach taken (at a high level)

Changes Made

Bullet list of specific changes — one bullet per logical change, not per file:

• Added [X] to handle [Y]
• Refactored [A] to reduce [B]
• Removed [C] as it was replaced by [D]
• Updated [E] to fix [F]

Screenshots / Demo

[If UI change: include before/after screenshots or a screen recording] [If API change: include example request/response] [If no visual change and no API contract change: omit this section entirely — do not leave it as a placeholder]

How to Test

Step-by-step instructions a reviewer can follow:

1. [Setup step if needed]
2. [Action to take]
3. [What to verify]
4. [Edge case to check]

Include any specific commands, test data, or environment flags needed.

Testing Checklist

• Unit tests added/updated
• Integration tests added/updated
• Edge cases covered
• Manual testing completed
• No regressions in existing tests

Reviewer Notes

Flag anything that warrants extra attention:

• Areas of uncertainty where a second opinion is welcome
• Deliberate trade-offs made (and why)
• Out-of-scope items noticed but not addressed
• Dependencies on other PRs (link them)

Related

• Closes #[issue number] (if applicable)
• Related to #[PR/issue number]

Deeper Materials

This skill ships with support files — use them when they are available:

• references/reviewer-empathy.md — PR Descriptions as Review Navigation. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
• templates/pr-template.md — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

Dimension	0	5	10
Why over what	Description only restates the diff; no motivation given	The what is clear, but the why is thin or generic ("improves the code")	Problem, goal, and approach are explicit; the description adds context the diff cannot convey
Title & structure	Single unstructured paragraph; title vague, missing a type prefix, or over 72 characters	Structured with headers, but the title or section usage slips (placeholder sections left in)	Valid type prefix, imperative mood, under 72 characters; sections let a reviewer navigate straight to what they need
Testing reproducibility	No testing steps	Steps exist but assume codebase familiarity or skip edge cases	Someone unfamiliar with the code can reproduce verification — commands, test data, flags, and at least one edge case included
Risk-calibrated reviewer guidance	High-risk PR with no reviewer notes, or notes that are pure boilerplate	Notes exist but name no specific trade-off, uncertainty, or out-of-scope item	Guidance matches risk: high-risk flags specific concerns and deliberate trade-offs; low-risk keeps notes to one line or omits them

Quality Checks

• Title is imperative mood and under 72 characters
• Summary explains what AND why (not just what)
• Changes list describes logical changes (not file-by-file changes)
• Title starts with a valid type prefix (feat / fix / refactor / chore / deps / config / hotfix) and is under 72 characters
• Testing steps are reproducible by someone unfamiliar with the code
• For high-risk PRs, Reviewer Notes flags at least one specific area of concern or deliberate trade-off; for low-risk PRs, Reviewer Notes is either omitted or kept to one line

Anti-Patterns

• Do not write a description that only restates what changed — explain why the change was made
• Do not skip the testing steps — reviewers need to know how to verify the change works
• Do not omit the reviewer notes for high-risk PRs — flag deliberate trade-offs and areas needing careful review
• Do not describe implementation details that are obvious from the diff — add context that the diff cannot convey
• Do not produce a single paragraph — structure with headers so reviewers can navigate to what they need

Usage Examples

• "Write a PR description for these changes" + [paste diff or description]
• "Draft a pull request for [feature]"
• "I need a PR description — here's what I changed"
• "Summarise these commits into a PR description"
• "Write the PR body for this branch"