explain-diff

name	explain-diff
description	explain-diff: explain a code change, diff, branch, or PR as a rich self-contained HTML page. Flags: --target <branch>, --pr <n>, --staged, --unstaged, --output <path>.

Explain Diff

Produce one teaching artifact: a long-page HTML file with Background, Intuition, Code, and Quiz. Not a PR description (make-pr) and not inline chat prose—the reader opens the file in a browser.

Flags

Flag	Effect
--target <branch>	Branch diff: git diff <branch>...HEAD. Default: main.
--pr <n|url>	PR diff via gh pr diff (and PR title/body for context).
--staged	git diff --cached only.
--unstaged	git diff only.
--output <path>	Write path. Default: /tmp/YYYY-MM-DD-explain-<slug>.html

Diff source is mutually exclusive. Use the first detected among --pr, --staged, --unstaged; otherwise --target. --pr without a number when not on a PR branch: try gh pr view to resolve; if it returns no PR, stop and ask.

Slug: short kebab from the change topic (e.g. rate-limit-api).

Step 1: Gather the change set

Collect diff text and identifiers (files, commits, PR number). If the diff is empty, stop: "No changes found to explain."

For --target, also run git log <target>..HEAD --oneline for narrative context.

Step 2: Legwork

Read surrounding code beyond the diff hunk lines—callers, types, tests, config—so Background can stand alone for a beginner and still narrow to what this change touches. Done when you can name the system before/after without guessing.

Step 3: Draft the four sections

Follow section rubrics, prose tone, diagram families, and quiz rules in ./REFERENCE.md. Order on the page: Background → Intuition → Code → Quiz.

Trace rule: claims about the change trace to diff hunks; claims about the surrounding system trace to code read in Step 2. A sentence that traces to neither gets cut or rewritten. Completion: every Background, Intuition, and Code claim traces to a hunk or a read file.

Step 4: Write HTML

Emit a single self-contained file: embedded CSS and JavaScript, table of contents, section headers, one scroll (no top-level tabs). Basic responsive layout. Apply the pre-save checklist in ./REFERENCE.md (especially pre / white-space on code blocks).

Write only to --output or the default under /tmp/ (or another path outside the repo). Never commit the HTML file.

Step 5: Report

Give the absolute path and a one-line open hint (open on macOS, xdg-open on Linux, start on Windows). Do not paste the full HTML into chat.

Constraints

• Never use ASCII art diagrams; use simple HTML diagram patterns from ./REFERENCE.md.
• Never commit, push, or open a PR as part of this skill.
• Quiz: five medium-difficulty multiple-choice questions with click feedback in the page—spec in ./REFERENCE.md.