Pull Request Description Craft

Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/pr-description-craft.md

↓ Facts as markdown all context files

```markdown

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

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

The order matters: reviewers read top-down and decide whether to keep reading after each section. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#1-the-wwht-template-what-why-how-test]

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

A PR has two audiences: [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#2-the-two-tier-reader-pattern-skimmers-above-nit-pickers-below]
- Skimmers - the manager, the on-call, the eventual archaeologist running git log six months from now. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#2-the-two-tier-reader-pattern-skimmers-above-nit-pickers-below]
- Nit-pickers - the assigned reviewer. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#2-the-two-tier-reader-pattern-skimmers-above-nit-pickers-below]

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

Screenshot discipline: [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]
- Two screenshots side by side: Before and After. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]
- Crop tight to the changed region. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]
- For dark-mode features, include both light- and dark-mode screenshots. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]
Recording discipline: [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]
- Use recordings for interaction flows, animation, or anything that can't be captured in one frame. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]
- Trim to ≤ 30 seconds. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers]

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#5-link-out-vs-inline-detail]
Link out: The full incident report; the original RFC; the customer ticket; the benchmark methodology; stack traces longer than 10 lines. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#5-link-out-vs-inline-detail]

6. Draft, blocked, and stacked signaling

[Draft] or use GitHub's native "Draft PR" toggle [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#6-draft-blocked-and-stacked-signaling]
[Do not merge] - for PRs that exist for discussion only [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#6-draft-blocked-and-stacked-signaling]
[Stacked on #1234] - depends on another PR [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#6-draft-blocked-and-stacked-signaling]

7. Stacked PRs

When a feature can't reasonably fit in one reviewable PR (~400 lines is the soft ceiling): [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs]
- PR #1: refactor / scaffolding - no behavior change. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs]
- PR #2: the substantive change - depends on #1. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs]
- PR #3: tests / docs / migration - depends on #2. [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs]
Mark each stacked PR's body with its position: [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs]

8. Checklists that get verified, not skipped

[ ] Code follows best practices [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped]
[ ] npm run lint passes locally [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped]
[ ] npm run test passes locally [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped]
[ ] Manifest version bumped in manifest.json and package.json [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped]
[ ] Screenshot added for any UI change [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped]

Anti-Patterns

Empty PR descriptions ("see commits") [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]
Bullet list of every changed file - the diff already shows this [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]
Screenshots without before/after [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]
"Tested locally" with no steps [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]
40-item checklist of every conceivable concern [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]
Massive PRs (1,000+ lines) - split into a stack [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]
Hiding the breaking-change disclosure - put BREAKING in the TL;DR [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns]

References

Graphite - Best practices for GitHub pull request descriptions [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#references]
GitHub Docs - Creating a pull request template [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#references]
Conventional Comments specification [archived source: https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#references]

Where this helps

Writing a PR description for a large feature that had to be split into a stack of dependent PRs, where reviewers need to know each PR's position in the sequence. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Deciding whether a piece of context (an incident report, an RFC, a stack trace) belongs inline in the PR body or linked out, based on how essential it is to the review decision itself. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Documenting a UI change so both the fast-skimming manager and the line-by-line reviewer get what they each need from the same description. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Disclosing a breaking change clearly enough that it can't be missed by a reviewer skimming only the TL;DR. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

How to apply this

Draft the description in WWHT order (What, Why, How, Test), since reviewers read top-down and decide whether to keep reading after each section. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Write for both audiences at once: a skimmable summary at the top for the manager or future archaeologist, and enough detail below for the assigned reviewer doing a line-by-line pass. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Include tight before/after screenshots (both light- and dark-mode where relevant) or a trimmed recording for any visual or interaction change, rather than describing the change in prose alone. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Split a change approaching the ~400-line soft ceiling into a stack (scaffolding, then substantive change, then tests/docs/migration), marking each PR's position and dependency explicitly in its body. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Common mistakes

Writing an empty PR description ("see commits") that forces the reviewer to reconstruct intent from the diff alone. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Padding the description with a bullet list of every changed file, when the diff already shows this. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Writing "tested locally" with no steps, leaving the reviewer unable to verify or reproduce the testing claim. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Hiding a breaking-change disclosure deep in the body instead of flagging it in the TL;DR where a skimming reviewer will actually see it. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

The WWHT template and two-tier reader pattern assume reviewers actually read top-down; a reviewer who jumps straight to the diff may never see carefully structured context at the top of the description. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Stacked PRs reduce individual PR size but add coordination overhead — a reviewer needs to track dependency order across multiple PRs, which is more cognitively demanding than reviewing one large PR in isolation. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Long verification checklists tend to get rubber-stamped rather than actually checked once they exceed a handful of items, undermining the goal of checklists that get verified, not skipped. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
The line-count soft ceiling (~400 lines) is a heuristic, not a hard rule — some genuinely atomic changes, like a large generated-file update or a bulk rename, exceed it without being meaningfully splittable into a reviewable stack. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

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