explain-diff

Explain diff

Flags

Flag	Default	Effect
--target <branch>	main	Explain <branch>...HEAD
--pr <n|url>	off	Explain one PR diff and metadata
--staged	off	Explain the index
--unstaged	off	Explain worktree changes
--output <path>	/tmp/YYYY-MM-DD-explain-<slug>.html	Set HTML path

The four source choices are mutually exclusive; conflicting or valueless flags are BLOCKED; bare --pr is the only value-less exception and may resolve the current branch PR. With no source flag, use the equivalent of --target main. Block when PR diff cannot be fetched. Missing optional PR metadata permits a diff-only page with no motive claims.

1. Lock source and output

Capture source identity, head SHA, exact diff, sorted paths, and SHA-256 diff hash. Empty diff is NO_CHANGES. Derive slug from sanitized branch name, PR number, or change-<head8>, capped at 40 characters.

Resolve output to an absolute path outside the repo; an explicit in-repo path is BLOCKED, never relocated. Create a missing parent. Block before overwriting a user-supplied existing file. A default output may replace only a prior artifact containing this skill's generator marker.

Record: source/hash | theme(name/paths/path-hash/gate) | evidence | output | gate | verification | terminal. Gate is lock, research, build, or verify. Persist beside the output as <output>.ledger after every gate and completed theme. Resume an active ledger only when output and source hash match; otherwise BLOCKED. Remove on success.

Done when source and safe output are immutable.

2. Group and research

Assign every changed path to a functional theme before reading surrounding code. For more than 50 paths, explain themes through representative hunks and include every sorted path without truncation. Represent a rename as old → new; list generated or binary paths under those themes and make no behavioral claim without text hunks. Give path-only inventory rows data-hunk="<path>:inventory". Use at most 12 themes, three surrounding files per theme, and 30 surrounding files total. Read direct definitions, callers, contracts, tests, and config only when a planned claim needs them.

Done when every path has a theme and each planned claim has a hunk or read-file pointer.

3. Build the teaching page

Load ./REFERENCE.md. Write one HTML file in this order: Background, Intuition, Code, Quiz. Include a table of contents, inline CSS and JavaScript, responsive layout, and only HTML or inline-SVG diagrams. Code sections group by theme, with the complete inventory for large diffs.

Every factual sentence about the change traces to a hunk. Every system claim traces to a surrounding file. Remove unsupported intent, motive, or PR claims.

Done when the file exists with all four non-empty sections and five grounded quiz questions.

4. Verify and report

Apply the reference checklist. Verify no external asset URL, all anchors, generator marker, code whitespace, evidence pointers, and quiz answer feedback. When a browser tool exists, load the file and test one correct and one incorrect answer for every question; otherwise parse JavaScript and HTML and disclose verification: static-only. A browser run reports verification: browser. Recompute the live source fingerprint before SUCCESS; drift is BLOCKED so the page never mixes snapshots.

After interruption, compare source hash and ledger. Restart changed themes; otherwise continue at the first incomplete gate.

Report absolute path, source, theme and file counts, quiz count, and verification level. Do not paste the HTML. Terminal values are SUCCESS, NO_CHANGES, and BLOCKED. Never commit, push, or mutate a PR.