CommunityWriting & Editinggithub.com

pr-explainer

Explain a pull request, bug fix or local change to a teammate, pitched at a junior engineer, as one self-contained HTML page (default) or a Markdown handover (--md). Covers a feature (why, architecture, flow, key code, verification) or a bug fix (symptom, root cause, fix, proof). Use when asked to "explain this PR/fix/change", "write a walkthrough", "write a handover", "create a review guide", or before handing work over. Flags - --concise for a two-minute version, --local for uncommitted or unpushed work, --md for HANDOVER.md-style Markdown.

What is pr-explainer?

pr-explainer is a Claude Code agent skill that explain a pull request, bug fix or local change to a teammate, pitched at a junior engineer, as one self-contained HTML page (default) or a Markdown handover (--md). Covers a feature (why, architecture, flow, key code, verification) or a bug fix (symptom, root cause, fix, proof). Use when asked to "explain this PR/fix/change", "write a walkthrough", "write a handover", "create a review guide", or before handing work over. Flags - --concise for a two-minute version, --local for uncommitted or unpushed work, --md for HANDOVER.md-style Markdown.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more Writing & Editing skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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 gh CLI available, get the details with gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files and the diff with gh pr diff <url>. Read surrounding code at the PR's head commit (git show <headRefOid>:<path>), not local HEAD.
    • With no PR, or no gh: explain the local change. Use git diff <base>...HEAD for commits and git diff plus git status for uncommitted work, where <base> is the default branch or the first commit.
  • --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 file HANDOVER.md in 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, then git 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

  1. What went wrong: the symptom, where it was seen, what was ruled out.
  2. Root cause: the exact place the data or flow breaks (file:line), with a visual if it helps.
  3. The code that caused it: one or two snippets.
  4. The fix: a diff snippet and why it works. Name side effects it also fixes.
  5. How we know: a regression test that fails before and passes after, full-suite counts, a manual check.
  6. Takeaways: 2–4 lessons a junior can reuse elsewhere.

Feature

  1. Why: the problem or goal, with evidence.
  2. Where it sits: architecture or module context (diagram), plus what is intentionally unchanged.
  3. How it flows: steps or a flowchart linked to the code cards.
  4. Code walkthrough: one card per important file, in flow order.
  5. Behaviour to know: edge cases, states, failure modes (a table if there are more than 3).
  6. Verification: the latest run only.
  7. 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

ContentUse
Module or service architecture, who calls whom, request sequenceMermaid flowchart / sequenceDiagram (≤ ~12 nodes)
One branch that behaves differently before and afterBefore/after table or a small static SVG
Data passing through stages, values dropped by a filterA table of example inputs → outputs, before vs after
States, commands, risks, contractsTables

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, or local-<short-desc>. Keep it out of git: if git check-ignore -q .pr-review/ fails, append .pr-review/ to .git/info/exclude. Don't edit .gitignore unless asked.
    • Code snippets: <pre><code class="language-<lang>">…</code></pre>, HTML-escaped. For a fix diff, use language-diff with -/+ lines.
    • Mermaid: <pre class="mermaid">…</pre>. Never hard-code colours.
  • 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 (open on macOS, start on Windows, xdg-open on 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.

Related Skills