Explain diff

A diff shows what changed. It never shows why or what to worry about. This skill recovers both — intent and risk. It explains; 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) — the work in this session: the current branch against main plus uncommitted changes, or the session's own commits when it worked on main; 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), or the session's own commits when it worked on main; read their 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. Unless this session is already a fresh agent that has not seen the change, delegate the whole gather-and-draft pass to one whenever 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, and check its draft's claims against the code before presenting it — a cold reader misreads too.
2. Name the change's goal and the problem it solves, then the separable parts that deliver it. Group hunks by part, not by file — a part 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 part, 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), every site that branches on what changed (an instanceof, a code match, a catch) whether or not the diff touches it, 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, generated files none. Measure length against the change's meaning, not its line count.

Output