# Pull Request Description Craft > ```markdown Parent: [Writing and Documentation](https://llms-explorer.com/tree/writing-and-documentation/) · 13 facets · 52 facts · page: https://llms-explorer.com/tree/pull-request-description-craft/ ## 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: `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: — 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. — 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. — 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: — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers` - Crop tight to the changed region. — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers` - Recording discipline: — 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. — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#3-beforeafter-evidence-screenshots-recordings-numbers` - Trim to ≤ 30 seconds. — 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. — 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. — 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 — 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 — 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 — 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): — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs` - PR #1: refactor / scaffolding - no behavior change. — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs` - PR #2: the substantive change - depends on #1. — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs` - PR #3: tests / docs / migration - depends on #2. — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#7-stacked-prs` - Mark each stacked PR's body with its position: — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped` - [ ] npm run lint passes locally — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#8-checklists-that-get-verified-not-skipped` - [ ] npm run test passes locally — 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 — 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 — 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") — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns` - Screenshots without before/after — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns` - "Tested locally" with no steps — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns` - 40-item checklist of every conceivable concern — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns` - Massive PRs (1,000+ lines) - split into a stack — 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 — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#anti-patterns` ## References - Graphite - Best practices for GitHub pull request descriptions — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#references` - GitHub Docs - Creating a pull request template — source: `https://llms-explorer.com/sources/mdb-context-hub/pr-description-craft/#references` - Conventional Comments specification — 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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(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](https://llms-explorer.com/tree/pull-request-description-craft/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)*