Explain Branch

Builds on explain-diff: same target resolution, same rendered page (CSS/JS/quiz mechanics), same writing voice. The difference is structural — a branch with several commits usually tells a story of how a feature was built step by step, and the article should read that way: one chapter per meaningful step, not one undifferentiated diff.

Output is still critique-free: a teaching document, not a review.

Workflow

Step 1 — Resolve the target

Same spec syntax as explain-diff (blank/"this branch", branch:foo/bar, mr:123, commit:abc). Run the same script, unmodified:

python3 ~/.claude/skills/explain-diff/scripts/resolve-target.py "<spec>"

Source BASE, HEAD_REF, LABEL, IS_SINGLE_COMMIT, MR_NUM, MR_URL, MR_TITLE. If IS_SINGLE_COMMIT is true (the user gave a commit: spec), there is no multi-commit story to tell — stop here and just run the explain-diff skill instead of this one. MR_NUM/MR_URL/ MR_TITLE are only set for an mr: spec — see explain-diff's SKILL.md for how to use them in the subtitle.

Step 2 — List the commits and classify each one

git log --reverse --format='%H %s' "$BASE".."$HEAD_REF"
git diff --shortstat "$BASE".."$HEAD_REF"

This is the chronological build order (oldest first) — the order the chapters will follow. For each commit, look at its subject and its actual diff (git show <hash>) and classify it:

• Substantial — introduces or changes behavior, adds a new file/service, wires things together, fixes a real bug, meaningfully reshapes a schema/contract. Deserves its own chapter.
• Trivial — pure rename/move with no logic change, formatting/lint-only, a typo fix, a docs-only edit, a generated-file regen with no accompanying hand-written change. Does not get its own chapter or quiz question. This repo uses Conventional Commits (see the project's /commit skill) — a chore/docs/style type is a hint worth checking, not a verdict; a chore can still be substantial (e.g. deleting a real feature), and a refactor can still be trivial (e.g. a rename). Judge from the diff, not the prefix.

If a trivial commit is directly relevant to a neighboring substantial chapter (e.g. a rename that sets up the next commit's change), fold one sentence about it into that chapter's prose instead of giving it a heading.

Fallback rule: if there is only one substantial commit (0 or 1), there's no real step-by-step story — stop and run the explain-diff skill instead, treating $BASE..$HEAD_REF as one flat diff. Chaptering only pays off with 2+ substantial steps.

Step 3 — Explore surrounding code

Same as explain-diff Step 3: read touched files in full, skim callers/callees, enough to explain the system each chapter's change lives in — not just the lines that changed.

Step 4 — Write the content spec

Use render.py — the same one, unmodified path:

python3 ~/.claude/skills/explain-diff/scripts/render.py spec.json

It now additionally supports a "quiz" array on a section itself (not just top-level): when present, it renders as a "Check your understanding" mini-quiz right under that section, instead of a trailing global quiz block. See its --help for the full section/quiz JSON shape.

Structure the spec's "sections" as:

1. Intro (id: "intro") — the same kind of Background+Intuition content explain-diff would write for the whole feature: the problem being solved end to end, why it's worth knowing, and a one-line roadmap of the chapters to come (e.g. "This branch gets there in three steps: first ..., then ..., finally ..."). This is what keeps the "high-level view" intact even though the detail is now chaptered.
2. One chapter per substantial commit, in build order, id: "chapter-N", heading titled by what the commit does (not its raw subject line) — e.g. "Chapter 2: Making x-retry-policy mandatory", not "Chapter 2: 9f8e7d6". Give the section a "commit" field — e.g. {"hash": "9f8e7d6", "subject": "refactor(ABC-123): make the retry header explicit, skip requests without one", "url": ..., "diffstat": {...}} — render.py renders the muted citation line under the <h2> automatically; don't hand-write that <p> into the chapter's own "html". "hash" is the short SHA from Step 2's git log; "diffstat" is git show --shortstat <full-sha> parsed the same way as the branch-wide one below. Only set "url" when MR_URL is set (an MR-context run) — strip the trailing /-/merge_requests/$MR_NUM off MR_URL to get the project's base URL, then url = "<project-base>/-/commit/<full-sha>" (full SHA, from git log --format='%H %s'). For a plain branch, there is still a commit page whenever git remote get-url origin is a GitLab/GitHub remote — normalise it (git@host:group/repo.git → https://host/group/repo, drop a trailing .git) and build <base>/-/commit/<full-sha> for GitLab, <base>/commit/ <full-sha> for GitHub. Losing every per-chapter link because there is no MR is an oversight, not a rule. Omit "url" only when the remote is missing or not http-resolvable; the subject then renders as plain text. Each chapter's html covers that commit's own intuition + a code walkthrough of its diff only (use git diff <hash>^..<hash> to get exactly that commit's change) — do not re-explain ground already covered by an earlier chapter. Attach that chapter's own "quiz" array (1–3 questions) only if there's something commit-specific worth testing — skip the quiz on a chapter that's mostly scene-setting.
3. Summary (id: "summary") — how the chapters combine into the finished feature; a final diagram if useful; loose ends the commits themselves flagged (TODOs, follow-up tickets).

Leave the spec's top-level "quiz" empty — all questions live on their chapter.

Content rules (which fields take markup and which are plain text, diagrams, code-block language classes, .callout/.diagram divs, Kleppmann-ish voice) are identical to explain-diff's — see its SKILL.md for the full list; not repeated here.

One thing the chapter structure makes worse, so it is worth repeating: a diagram per chapter is not the goal. Chapters tempt you into one figure each for symmetry, which is exactly the padding explain-diff's "judgement, not quota" rule warns about — and consecutive chapters of the same feature tend to want the same diagram, which fails its "is this a different question?" test. Prefer one good diagram in the chapter that introduces a structure, and refer back to it from the later ones rather than redrawing a near-copy. If a later chapter genuinely changes the shape of something an earlier chapter drew, redraw it there as a before/after pair — same ids, same roles, the two tokens adjacent — rather than as a near-copy several chapters apart, which the reader cannot compare at all.

Set "slug" to $LABEL. Build "subtitle" mostly like explain-diff (link the MR via [MR !$MR_NUM: $MR_TITLE]($MR_URL) when set, backtick the branch), but drop the trailing commit-hash segment entirely — with chapters in play there's no single commit to name up top, each chapter already cites its own (see above). So the whole-branch subtitle is just [MR !$MR_NUM: $MR_TITLE]($MR_URL) · `branch` (or just `branch` with no MR). Parse Step 2's git diff --shortstat into the spec's top-level "diffstat" field, same as explain-diff — render.py appends it to the end of the subtitle automatically.

Step 5 — Render & open

python3 ~/.claude/skills/explain-diff/scripts/render.py spec.json
open "$FILE_PATH"

Same length-bias guard as explain-diff, now checked across all questions (top-level plus every chapter's) as one pool — don't reach for --allow-length-bias unless you're sure the flagged questions are fine.