Explain Diff
Produce one
teaching artifact: a long-page HTML file with Background,
Intuition, Code, and Quiz. Not a PR description (
) and not inline chat
prose—the reader opens the file in a browser.
Flags
| Flag | Effect |
|---|
| Branch diff: . Default: . |
| PR diff via (and PR title/body for context). |
| only. |
| only. |
| Write path. Default: /tmp/YYYY-MM-DD-explain-<slug>.html
|
Diff source is mutually exclusive. Use the first detected among
,
,
; otherwise
.
without a number when not on a PR
branch: try
to resolve; if it returns no PR, stop and ask.
Slug: short kebab from the change topic (e.g.
).
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
, 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
. Order on the page: Background → Intuition → Code → Quiz.
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
(especially
/
on code blocks).
Write only to
or the default under
(or another path
outside
the repo). Never commit the HTML file.
Step 5: Report
Give the absolute path and a one-line open hint (
on macOS,
on
Linux,
on Windows). Do not paste the full HTML into chat.
Constraints
- Never use ASCII art diagrams; use simple HTML diagram patterns from
.
- 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 .