explain-diff

Explain a Change

Produce one self-contained HTML page that explains a code change well enough that someone who did not write it could defend it, ending in a quiz that tests whether they actually followed.

Scope

Set the target from $ARGUMENTS:

• No argument — uncommitted working tree against HEAD. Use git status --short and git diff (add git diff --cached if anything is staged).
• One ref (abc123, main) — that ref against the working tree, or against HEAD if the tree is clean.
• A range (main..HEAD, abc123..def456) — use it as given.

New files are part of the change. git diff shows nothing for an untracked file, so a change that only adds scripts looks empty. Always read git status --short for ?? entries and treat every new file as an addition to explain: read it in full, since there is no diff to read. A new robustness script is exactly the kind of change worth explaining, and it is the one the diff will hide.

Stop only when git status --short and the diff are both empty.

Read from scratch

Work only from the code and the diff. If the conversation already contains an account of this change — yours or the user's — ignore it and read the files. A summary written earlier is a hypothesis, not evidence.

Do not stop at the diff hunks. For every changed block, read the function, script, or stage that contains it, and read what consumes its output. A three-line addition to a pipeline stage is usually only comprehensible from the two files on either side of it.

Verify before you claim

The single most common failure here is reporting a change in results that did not happen, or missing one that did. Check, do not infer:

• Generated files. Tables, .tex bodies, and rendered figures often show as modified when only a timestamp comment or a nondeterministic tie-break changed. Diff them and look at what actually differs before calling it a result change.
• Binary artifacts. If an image changed, compare both versions visually. The old version lives in git rather than on disk, so extract it first — git show HEAD:path/to/figure.png > /tmp/old-figure.png — then read the extracted copy alongside the working-tree one. A re-render with identical content is not a finding.
• Logs. Compare sample sizes, observation counts, and headline coefficients between the old and new run. Identical numbers are the proof that an added block was inert; do not assert it from code reading alone.
• Numbers you quote. Every figure in the page should come from an output file you opened, not from the prose of the diff. If the change writes a new CSV, read it.
• Samples. When a new block filters data, compare its filter line by line against the filters of the existing estimation samples. Differences of one clause are the interesting ones.