| name | super-good-pr |
| description | Use this skill when writing, polishing, or maintaining a pull request description, including drafting a PR body, opening a PR, rewriting a weak one, updating or refreshing a description after new commits or a rebase, keeping a PR body accurate, or when asked to make a PR "good" or "a banger". Produces reviewer-first descriptions that lead with why, prove every claim with evidence, name the decisive files and invariants, and state the real blast radius. Activates on mentions of write a PR, PR description, draft a PR, open a pull request, polish this PR, make this PR good, banger PR, PR body, update the PR description, refresh the PR body, keep the PR description accurate, describe these changes, or PR writeup. |
Super Good PR Descriptions
A PR description is read by a human who has to rebuild your mental model from zero and decide whether to trust it. The job is to hand them that model fast, prove the parts they'd doubt, and say plainly what you didn't do.
Core insight: lead with why, prove with evidence, state the real blast radius. A changelog tells the reviewer what moved. A super-good PR tells them what to believe, where to look, and what could still bite. The difference is entirely in altitude and receipts, not length.
How to read this skill: the spine below is a map, not a script. Real PRs drop sections that don't apply and add domain-specific ones that do. A one-file fix doesn't need a rollout-sequencing section; a migration does. Match the shape to the change. The non-negotiables carry the weight; the section order is just a reliable way to deliver them.
The non-negotiables
These are what make a description land. If a section doesn't serve one of these, cut it.
- Open with the mental model, not the diff. First paragraph says what this is and, when there's a naive version a reader would assume, why that version is wrong. "IP/CIDR allowlists are the wrong primitive here: behind a shared cloud edge, allowing an IP means allowing every tenant on it." Now the reviewer knows why the code looks the way it does before they read a line of it.
- Describe the system, not the session. The body explains what the code does now and why, never the journey. No "then we refactored", no review round-by-round, no tooling provenance. Development history is sludge to a reviewer; the making-of belongs in the chat synthesis, not the artifact. This binds hardest when you edit an existing body: an approach you abandoned mid-PR is not news, so "an earlier version of this change kept X" and "originally this did Y" turn the description into a revision log about you. When a rejected alternative genuinely helps a reviewer, argue it in the present tense as a property of the system, so "accepting
gradial buys nothing, because the namespace is empty on every cluster" rather than "we used to accept gradial". The 🔁 What changed since the last review round section is the only place a delta belongs, it is scoped to what reviewers asked for, and it does not exist on a first-round PR.
- Name the invariant everything rides on and tell reviewers to anchor on it. Most PRs have one property that, if broken, breaks everything: an ordering, a fail-closed default, an idempotency key. Say it out loud. "Anchor on one property: no upstream socket is opened until every check passes." That sentence directs the entire review.
- Name actual files, functions, and patterns.
proxy.rs, resolvePolicy(), ON CONFLICT (id) DO UPDATE, "the write → audit → revoke ordering." A reviewer should be able to navigate the diff cold from your prose. Vague nouns ("the handler", "some validation") make them hunt.
- Prove every claim with a receipt. Not "tests pass" but
cargo test -p proxy → 98 passed, 0 failed. Not "it's safe" but the test that pins it. Assertions are free; evidence is the whole point of the section.
- State the real blast radius. What's untouched ("default deployments get none of this"), what's deliberately not built (the dangerous-but-obvious alternative you rejected, and why), and what's a known gap shipping as a follow-up. Hiding the gaps reads as not knowing them.
- Close the gap instead of disclosing it. A gap you could have fixed in the time it took to write the paragraph explaining it should have been fixed. Before describing any gap, ask whether it is genuinely blocked (needs an approval, a live install, an external system, a decision that is not yours) or merely unfinished. Unfinished work gets finished before the PR opens. What survives is a real boundary, so state it as a fact about the system and what settles it, never as a confession.
- Never label your own writing honest. No "Honest gaps", no "the honest answer", no "to be honest". Honesty is the floor, not an achievement, and announcing it reads as unconfident and implies the rest might not be. Say what was done and what was not, and let the receipts carry the credibility.
The spine
Use the headers that carry weight for this change. Each is a ## with a semantic emoji (palette below).
# <emoji> <short evocative title>: a noun phrase that names the thing, not a verbatim copy of the commit subject. "Per-tenant rate limiting, end to end", not "feat(api): add limiter".- Context blockquote (
>): one to three lines orienting the reader. For a standalone PR, where it sits and what it assumes. For a stack, the nav line (see Stacked PRs and granularity below).
## 💡 What this is: the core, two to four sentences. Lead with the mental model; kill the naive primitive here if there is one.## 🤔 Why we need it & what it replaces: the old world and why it falls short; what's deliberately not built and why the obvious version was dangerous; the blast-radius framing ("dark by default", "non-X deployments untouched").## 🎯 The invariant / anchor (when one property carries the change): the single thing to anchor the review on. Optional but powerful; skip it if the change has no single crux.## 🛠️ How it works: a numbered, sub-headed walkthrough a reviewer follows cold. Name files. Name patterns by name. This is where most of the body lives. Topology, flow, and ordering changes get a diagram here (see Diagrams and visual enrichment below).- Domain deep-dives (as needed):
## 🗄️ The database, ## 🔗 Identity, end to end. Add one when a subsystem deserves its own focused pass.
## 🚦 Rollout sequencing (and why it's safe) (for anything deployed): the order of operations, what's safe to stop at, what the old path keeps doing, and the expected day-one surprises: the alert that fires legitimately, the manual step that remains.## 🔁 What changed since the last review round (on re-review): the delta. Credit reviewers by handle. Mark security/critical fixes (🛡️ / 🚨). This is how a re-reviewer reloads without re-reading.## 🧪 Validation: the receipts. Test suites with PASS counts, typecheck clean, render/lint green; one ⚠️ line for what's not covered, with the backstop and the open follow-up.## 🔍 What reviewers should focus on: the three-to-five trickiest surfaces, bulleted. End with what's intentionally out of scope. Consider closing by inviting the strongest objection: name the one counter-example that would change the design, and ask for it.
Evidence, not assertion
The Validation section is where trust is won or lost. Rules:
- Show the command and its result, not a summary of the result.
pnpm turbo typecheck across the changed package and its dependents → 112 tasks clean.
- Count things. "25 passed", "98 passed, 0 failed", "12 passed (dark-by-default, label-gate dependencies, patch ordering...)". The parenthetical says what the count proves.
- One
⚠️ line about a real gap beats ten green checks. "Local integration tests stay blocked by a local socket conflict; the CI job is the backstop, and a dedicated CI job for them is an open follow-up." That single line builds more trust than the whole rest of the section.
- If you didn't verify something, say so. Never imply a check ran that didn't.
- Receipts are keyed to a SHA. Any rebase, squash, or amend expires them, so re-run the gates against the new head and re-stamp the body. Stale green is a lie with a timestamp.
- Prefer integration-level proof with before/after state over local-test narration. If the PR ships a guard, show the guard tripping, because the induced failure is the receipt.
- After posting or editing, read the rendered body once. That pass catches quoting mangles, stale timestamps, and claims the final diff no longer supports.
Diagrams and visual enrichment
When a PR changes topology (services, request paths, data flow, state machines, deployment shape), prose makes the reviewer rebuild the picture in their head. Hand them the picture instead. GitHub renders ```mermaid fenced blocks natively, so a diagram costs nothing to ship and lives in the body itself.
| Change shape | Visual |
|---|
| Service/network topology, request path changes | Mermaid flowchart, before/after pair |
| Protocol, handshake, cross-service call order | Mermaid sequenceDiagram |
| State machine or lifecycle changes | Mermaid stateDiagram-v2 |
| Schema relationships, new tables/FKs | Mermaid erDiagram |
| Rollout phases and gates | Mermaid flowchart with the safe-stop points |
| UI changes | Screenshot or short clip, drag-dropped as attachment |
Rules that keep diagrams doing real work:
- Mermaid first. It renders natively, survives branch deletion, edits like text on later refreshes, and never 404s. Reach for an image only when mermaid can't express it.
- Before/after beats single-state. For a topology change, two small diagrams (old path, new path), or one diagram with the removed edge visibly styled out, show the delta the way a diff shows code.
- Draw at the invariant's altitude. The diagram shows the property the review anchors on: the new hop, the moved boundary, the enforced ordering, never every box in the system. If it needs a legend, it's too big.
- A diagram is a factual claim. A redesign that changes the shape expires it exactly like a receipt, so refresh it with the rest of the body, and include it in the post-edit rendered-body read (a mermaid syntax error renders as an ugly error block, not a diagram).
- SVG caveat. GitHub's drag-drop attachments accept PNG/JPG/GIF/MP4 but not SVG. An SVG must live in the repo and be referenced by URL, which couples the body to a file that can move or vanish, so prefer mermaid, or export to PNG and attach.
- Decorative diagrams are slop. A diagram restating a trivial diff ("handler calls service") costs reviewer time instead of saving it. Draw only what prose can't carry in one read.
Maintaining the body
The body outlives the push that created it. It's a document with a truth obligation, and often one a human has invested taste in.
- Read the live body before every edit. Update by surgical string edits; regenerating from scratch destroys human-crafted prose and reads as vandalism. Fetch the current body and edit it as a file (
gh pr edit --body-file), since inline shell strings are where quoting mangles come from.
- Refresh factual lines after every push. SHAs, receipts, counts, and "green CI" claims all reference a specific head. After a redesign mid-PR, re-derive every claim from
git diff origin/main...HEAD, because description drift is a blocking review finding.
- A freeze is absolute. "Don't update the desc" covers even a factually stale section, which waits for explicit go-ahead, and compliance is itself a receipt: "PR description untouched." Update frequency is the human's dial; when they cap it, accuracy notes move to the wrap-up instead.
- After a squash or history rewrite, the body carries the story the commits no longer tell: the design narrative of what and why, never a resurrected process diary.
- Bodies, titles, and drafts a human wrote are read-only unless they explicitly hand them to you.
- Before merge, a body that accreted as a receipt ledger gets one deliberate rewrite from the cold reader's seat.
Answering reviews
Replies are part of the PR's prose surface, with the same voice and the same receipts.
- Every piece of feedback, every round, gets an itemized disposition visible on the PR: fixed (with the SHA), no action (with the reason, addressed to the reviewer), follow-up, or stale.
- A reply pairs what changed with the receipt that pins it: the fix commit or the regression test.
- Resolution belongs to the reviewer: answer the thread, don't self-resolve it.
- Trivial nits get taken, not argued. A reviewer calling the description inaccurate gets code-defect priority.
Emoji palette
Semantic, never decorative, never stacked. Section-semantic set that works:
💡 what · 🤔 why · 🎯 anchor/invariant · 🛠️ how · 🗄️ database · 🔗 identity · 🎫 issuance · 📡 serve/API · 🧹 cleanup/retention · 🚦 rollout · 🔁 what-changed · 🧪 validation · 🔍 reviewer-focus · 📌 follow-ups · 🛡️ security fix · 🚨 critical fix · 🏷️ labels · 🔄 reconnect/refresh.
The house palette is fair game when a header wants personality, one emoji per header, chosen because it means something.
Banned, the AI-slop set, never use: 🚀 ✨ 💯 🙏 👀 🎉 👍 🔥 (👀 is the tempting pick for reviewer-focus, so use 🔍 instead).
Voice and anti-slop
This section is the anti-slop authority for a PR body, and it wins outright on structure. Semantic emoji headers are required here, so no cleanup pass gets to remove them. Run deslop for the prose patterns (em dashes, rule-of-three, inflated significance, chatbot closers, "-ing" pseudo-analysis, copula avoidance, filler and hedging); its PR-body surface profile defers to this section on shape, leaving the palette above, the bold section leads, and the reviewer-focus and follow-up sections intact. A general-purpose humanizer pass without that profile strips emoji, boldface, and bold-led bullets on sight, which guts all three.
- Sentences resolve left to right. Never open one on a bare identifier, path, or SHA: lead with the English noun and demote the symbol into apposition, so "the backfill commit (
23581131)" rather than the bare hash. Never let That, It, or This be the subject of a sentence crossing a heading. Detail that a reader can skip belongs in parentheses; detail they must parse to follow the argument belongs in its own sentence.
- "Banger" is the quality bar, not vocabulary. Never write "this is a banger / gorgeous / sick / cinematic" into a PR body. Those are words for talking about the work, not in it. The bar means: leads with why, proves claims, states the real blast radius. Real PR voice is plain, root-cause-first, full sentences.
- Full sentences that build linearly. No fragment-style compression, no corporate slop ("in order to", "it should be noted"), no hedging ("just", "simply", "basically").
- No em dashes or en dashes, ever. They are the most reliable AI tell, so this is a boundary rather than a "use sparingly" preference. Replace each one with a period, a comma, a colon, or parentheses, whichever the sentence actually wants. Scan the body for
— and – before posting; a hit means it is not ready.
- The slop lexicon evolves with model generations (as of Jul 2026): the "it's not an X, it's a Y" cadence, and "load-bearing", a word that must never land in a PR body. House jargon is fine between agents; sweep it from anything a human reads.
- Never instruct yourself or a generator to be "concise" for a PR body, because compression produces reviewer-hostile paste. Size to understanding; chat length anchors don't govern artifacts humans read later. On a host whose defaults favor terseness, suspend that default explicitly for anything leaving the terminal.
- A generator drafting the body gets the real receipts enumerated and a no-invented-validation constraint; fact-check its output against the diff before posting, since generators drift on paths and claims.
- Tables only for enumerable facts: a profile→mode mapping, a port list, a pass/fail grid. Never pack reasoning into table cells; reasoning goes in prose.
- A generated-by attribution footer is fine to leave in, since many harnesses add one automatically.
When the repo has a PR template
Make the template sing; don't abandon it. Map this spine onto the repo's sections, so a Changes / Reason / Validation / Reviewer notes template absorbs the same content, just under its own headers. The non-negotiables don't change; only the section labels do. Keep any required checkboxes and metadata the template demands. If a required slot has no real value (no ticket, no linked issue), omit it; a fabricated ID reads as real and rots.
Stacked PRs and granularity
Granularity answers to reviewer cost, and it gets corrected in both directions. Phases are rollout gates inside one PR unless review domains or ownership force a split; live-ops work consolidates to one end-state PR. When you do split, split by proof, not by directory, and each layer's body states in one line what that PR proves. Split mechanics live in git and plan; this skill carries the body-side consequence.
A stack needs a nav blockquote at the top of every PR so a reviewer always knows where they are and what's landed:
> **Stack PR 2 of 4 · PROJ-481**: the policy engine.
> `#101` (data plane, ✅ merged) → **`#102` you are here** → `#103` (admin surface) → `#104` (client adoption).
> Rebased onto current `main`.
Each PR's "What this is" then says what the previous PR established and what this one adds, so the stack reads as one argument across several documents. End each with what's deferred to the next PR in the stack.
