prathamdby 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.