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.

Sections

Write these five, in order, under clear headings.

1. What this code did before. Explore the surrounding scripts. Do not rely on the diff alone. Establish what the code produced, what consumed it, and — where it matters — what it conspicuously did not produce.

2. What changed and why, in plain language. No code in this section at all. Prose only. Name the problem the change solves before describing the solution.

3. Consequences for the results. Which sample, which coefficients, which tables, and in which direction. Be specific about magnitudes. If the answer is that nothing changed, say so explicitly and prominently, then show the evidence — matching observation counts, matching coefficients, timestamp-only diffs. A reader must not have to infer "no effect" from the absence of a claim. Where a change adds something rather than altering something, say what is new and what sample it rests on.

4. Walkthrough of the changed code, grouped by purpose rather than by file. One group per job the change does, even when a single job spans two files. Quote the code in <pre> blocks with the file and line range above each. Explain the lines that are load-bearing and skip the ones that are not, and say why a line is there when the reason is not obvious from reading it.

5. Quiz. Five multiple-choice questions, medium difficulty — hard enough that answering requires understanding the substance, not gotchas.