Explain diff

A diff shows what changed. It never shows why, what to worry about, or whether you actually understood it. This skill recovers the first two — intent and risk — and then tests the third: you do not pass on a change whose explanation you cannot give. It explains and gates; it does not judge (that is review) or sell the change for merge (that is pr).

Written for readers who read code fluently. Explain the why and the risk, never the what — the diff carries the what. High-signal, not a tutorial: no beginner walkthrough, no narrating mechanics the diff already shows.

Two modes: Self (no argument) — current branch diff against main, including uncommitted changes; PR (URL or number) — someone else's PR.

Workflow

1. Gather the change and its intent. Intent is stated in spec IDs, design notes, ADRs, commit messages, or a linked issue — find it before inferring. Self: diff the current branch against main (git diff main...HEAD, plus git diff HEAD for uncommitted work); read git log main..HEAD for commit messages, and for an uncommitted change check the diff's own spec/doc hunks first — read those and the small contract files before the biggest code hunk, and treat them as the commit message you do not have. PR: fetch with gh pr diff <N> and read intent from gh pr view <N> — the description and any linked issue. Prefer stated intent to inferred; the code says what it does, never what the author meant. Delegate the whole gather-and-draft pass to a fresh subagent whenever one is available, whatever the diff's size — a session that touched the change explains its own mental model back, and the gaps it papers over are exactly the ones it cannot see. Hand the agent only where to look: repo or worktree path, diff range or PR number, and tooling quirks it would otherwise trip on (a shell proxy that rewrites command output, an unusual build). Never your intent, rationale, alternatives weighed, or findings — a cold reader that converges on your reading independently is signal; one you briefed is an echo. Run it on a balanced-tier model or better. Keep the comprehension gate in this session regardless: you cannot delegate answering it for yourself.
2. Name the one logical change and the problem it solves. Group hunks by logical change, not by file — a change that spans five files is one story, not five. Git's hunk-header heuristic can mislabel the enclosing function; verify against the file rather than trusting the diff's own labels.
3. For each logical change, give three things: the intent (what it is for), the load-bearing decision and the alternative not taken (why this shape), and the risk (what could break, what a reviewer should scrutinize).
4. Surface the non-obvious. Implicit contracts touched, invariants relied on, ordering or concurrency, migrations, trust dependencies (where one component assumes an invariant another enforces without checking it — especially across a process or network boundary), anything a careful reader would miss on a first pass.
5. Separate stated from inferred. Never present an inferred why as fact. A reverse-engineered intent no source confirms is a guess — mark it as one.
6. Stay high-signal. Omit what the diff makes obvious. Mechanical renames, moves, and reindentation earn one line, not a tour. Measure length against the change's meaning, not its line count — a 200-line reindent carrying fifteen lines of real signal warrants a short explanation, not a long one.

Comprehension gate