PR explainer
Produce one document that teaches a teammate a change: what was wrong or missing, how the system works around it, what the change does, and how we know it works.
Arguments
- Target: a PR number or URL, or nothing.
- With a PR and the
ghCLI available, get the details withgh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,filesand the diff withgh pr diff <url>. Read surrounding code at the PR's head commit (git show <headRefOid>:<path>), not localHEAD. - With no PR, or no
gh: explain the local change. Usegit diff <base>...HEADfor commits andgit diffplusgit statusfor uncommitted work, where<base>is the default branch or the first commit.
- With a PR and the
--local: use the local checkout even when a PR exists (unpushed work). Note on the page that it reflects local changes.--concise: a short version that reads in about two minutes. One visual at most, 3 snippets at most, no table of contents, 1–3 sentences per section.--md: write Markdown instead of HTML (default fileHANDOVER.mdin the repo root, unless the user names one). Use this for handovers and when a browser isn't handy.
Audience and voice
- The reader is a junior engineer on the team. Use short sentences, plain verbs, one idea per paragraph.
- Don't define basics (REST, SQL, JWT, React hooks) and don't use non-technical analogies. Keep it technical, with real module, function, route and field names and real numbers.
- Make the wording simple, not the content. Explain an unusual library call or pattern where it first appears.
- Write it as a final draft. Describe the current state directly. No changelog or "earlier we thought" wording.
- Be honest about certainty. Label unproven claims "likely, not yet confirmed".
Scope: explain the change, not the diff
- Pick the files that tell the story, and inside them only the lines that matter.
- Use 1–3 snippets per file, each under ~25 lines, with
...for elided parts. Give each one the file path and 2–4 sentences on what it does and why. - For a fix, show the code that caused the bug and the diff of the fix.
- Order code by runtime flow, not diff order.
- Skip plumbing, renames and formatting. Mention them in one line if a reviewer will see them in the diff.
1. Understand the change
- Read the diff and the surrounding code. Decide the mode:
- Feature: new behaviour or a large refactor.
- Bug fix: a symptom, a root cause and a fix.
- Find the latest verification run: test command and counts, and ideally proof that a new regression test fails without the fix and passes with it. If that proof doesn't exist and it's cheap, produce it:
git stash push -- <src files>, run the test, thengit stash pop. Also look for a manual or end-to-end check (CLI output, a request, a screenshot). Show only the latest run of each. - Use findings from the conversation (root-cause analysis, QA report, ticket) where they exist.
2. Skeleton
Every document starts with an eyebrow line (repo · PR #n · ticket, or repo · local changes), a plain-language title, and a 1–2 sentence lede.
Bug fix
- What went wrong: the symptom, where it was seen, what was ruled out.
- Root cause: the exact place the data or flow breaks (
file:line), with a visual if it helps. - The code that caused it: one or two snippets.
- The fix: a diff snippet and why it works. Name side effects it also fixes.
- How we know: a regression test that fails before and passes after, full-suite counts, a manual check.
- Takeaways: 2–4 lessons a junior can reuse elsewhere.
Feature
- Why: the problem or goal, with evidence.
- Where it sits: architecture or module context (diagram), plus what is intentionally unchanged.
- How it flows: steps or a flowchart linked to the code cards.
- Code walkthrough: one card per important file, in flow order.
- Behaviour to know: edge cases, states, failure modes (a table if there are more than 3).
- Verification: the latest run only.
- Reviewer takeaway: the mental model in 2–3 lines, and where to look hardest in the diff.
Handover additions (always include with --md; optional in HTML):
- How to run / test: exact commands.
- Assumptions made: decisions taken where the spec was silent, and why.
- Open questions for the business: ordered by impact.
- Risks and rollback: what could go wrong in production and how to revert.
- Next steps: what you'd do with more time.
Concise: just What went wrong / What and why, Root cause / How it works, The fix / Key code, and How we know.
3. Visuals: only when they explain something the text can't
| Content | Use |
|---|---|
| Module or service architecture, who calls whom, request sequence | Mermaid flowchart / sequenceDiagram (≤ ~12 nodes) |
| One branch that behaves differently before and after | Before/after table or a small static SVG |
| Data passing through stages, values dropped by a filter | A table of example inputs → outputs, before vs after |
| States, commands, risks, contracts | Tables |
In Markdown, use fenced ```mermaid blocks (GitHub renders them). Add animations only if the user asks.
4. Build
- HTML: start from
references/page-template.html(self-contained, light and dark mode, Mermaid and highlight.js from a CDN). Save to.pr-review/<name>.html, named after the ticket or PR, orlocal-<short-desc>. Keep it out of git: ifgit check-ignore -q .pr-review/fails, append.pr-review/to.git/info/exclude. Don't edit.gitignoreunless asked.- Code snippets:
<pre><code class="language-<lang>">…</code></pre>, HTML-escaped. For a fix diff, uselanguage-diffwith-/+lines. - Mermaid:
<pre class="mermaid">…</pre>. Never hard-code colours.
- Code snippets:
- Markdown (
--md): plain GitHub-flavoured Markdown, same skeleton, no HTML.
5. Check once
- HTML: if a browser tool is available, open the page once at desktop width and once at ~400px. Check that Mermaid renders and code is highlighted, fix what you saw in one pass, and don't loop. Otherwise say it wasn't previewed and give the command to open it (
openon macOS,starton Windows,xdg-openon Linux). - Re-read every
file:line, number and command on the page against the code. Facts must be exact.
6. Report back
Reply with:
- the file path
- the mode, and the sections covered
- the visuals used and what each explains
- which verification run the document shows
- anything labelled "not yet confirmed"
Never edit a PR body, post a comment or push anything without asking first.