Pull Request Description Craft

Parent: Writing and Documentation · researched 2026-05-29T18:28:33.387Z· 8 sources · 10 concepts · skill pr-description-craft

```markdown

1. The WWHT template — What, Why, How, Test

The order matters: reviewers read top-down and decide whether to keep reading after each section. [source]

2. The two-tier reader pattern — skimmers above, nit-pickers below

A PR has two audiences: [source]
Skimmers - the manager, the on-call, the eventual archaeologist running git log six months from now. [source]
Nit-pickers - the assigned reviewer. [source]

3. Before/After evidence — screenshots, recordings, numbers

Screenshot discipline: [source]
Two screenshots side by side: Before and After. [source]
Crop tight to the changed region. [source]
For dark-mode features, include both light- and dark-mode screenshots. [source]
Recording discipline: [source]
Use recordings for interaction flows, animation, or anything that can't be captured in one frame. [source]
Trim to ≤ 30 seconds. [source]

5. Link-out vs inline detail

Inline: The rationale for the design decision; the error message or log line; the before/after screenshots; a 3-line code snippet. [source]
Link out: The full incident report; the original RFC; the customer ticket; the benchmark methodology; stack traces longer than 10 lines. [source]

6. Draft, blocked, and stacked signaling

[Draft] or use GitHub's native "Draft PR" toggle [source]
[Do not merge] - for PRs that exist for discussion only [source]
[Stacked on #1234] - depends on another PR [source]

7. Stacked PRs

When a feature can't reasonably fit in one reviewable PR (~400 lines is the soft ceiling): [source]
PR #1: refactor / scaffolding - no behavior change. [source]
PR #2: the substantive change - depends on #1. [source]
PR #3: tests / docs / migration - depends on #2. [source]
Mark each stacked PR's body with its position: [source]

8. Checklists that get verified, not skipped

[ ] Code follows best practices [source]
[ ] Tests are good [source]
[ ] npm run lint passes locally [source]
[ ] npm run test passes locally [source]
[ ] Manifest version bumped in manifest.json and package.json [source]
[ ] Screenshot added for any UI change [source]

Anti-Patterns

Empty PR descriptions ("see commits") [source]
Bullet list of every changed file - the diff already shows this [source]
Screenshots without before/after [source]
"Tested locally" with no steps [source]
40-item checklist of every conceivable concern [source]
Massive PRs (1,000+ lines) - split into a stack [source]
Hiding the breaking-change disclosure - put BREAKING in the TL;DR [source]

References

Graphite - Best practices for GitHub pull request descriptions [source]
GitHub Docs - Creating a pull request template [source]
Conventional Comments specification [source]

Children

WWHT template (What/Why/How/Test) (frontier)
Two-tier reader pattern (skimmers vs nit-pickers) (frontier)
Before/after screenshots and recordings (frontier)
Link-out vs inline detail (frontier)
Reviewer shopping and CODEOWNERS (frontier)
Draft/blocked/stacked signaling (frontier)
Stacked PR workflow (frontier)
Verifiable PR checklists (frontier)
PR title as squash-commit subject (frontier)
Conventional Comments for review threads (frontier)

Frontier under this node: Before/after screenshots and recordings, Conventional Comments for review threads, Draft/blocked/stacked signaling, Link-out vs inline detail, PR title as squash-commit subject, Reviewer shopping and CODEOWNERS, Stacked PR workflow, Two-tier reader pattern (skimmers vs nit-pickers), Verifiable PR checklists, WWHT template (What/Why/How/Test)

← the whole tree · 3D view· how to read this page