Explain diff

The One Principle

Build genuine understanding first, then explain it. The document exists so the reader can pass a quiz about the change without opening the files — and honestly could not before reading it. Inspired by Geoffrey Litt's explain-diff: understanding, not correctness, is the bottleneck of agent-written code.

The default reader is the author-practitioner: someone who works on this codebase and is about to review, merge, or defend this change. Skip beginner background; include behavior deltas, failure modes, and design rationale.

Honesty rules apply throughout:

• Never present a suspicion as a confirmed bug — frame it as an attention pointer.
• Distinguish stated intent (commit messages, PR body) from your inferred interpretation.
• Quote code verbatim only — never paraphrase, re-indent, or reconstruct from memory. Every quoted block must survive comparison against the actual file.
• Do not invent content for a section with nothing to say — omit the section.

Parse Arguments

Argument	Type	Description
(none)	—	Explain the working diff: git diff HEAD plus branch commits vs the default branch
PR number	e.g. 42	Explain that PR via gh pr view / gh pr diff
commit / range	e.g. a1b2c3d, main..feat/x	Explain that commit or range
path	e.g. src/auth/	Restrict the diff to this path

Step 1: Acquire the Diff

Resolve the target and gather, in one pass:

git diff HEAD                                   # or: gh pr diff {n} / git diff {range}
git log --oneline {range}                       # commit messages = stated intent
gh pr view {n} --json title,body 2>/dev/null    # PR mode only
git diff {range} --stat                         # file count, +/- totals for the metabar

Step 2: Investigate Before Writing

Do NOT start writing the document from the diff alone.

1. Read every hunk plus its enclosing function/class (Read the file, not just the hunk).
2. Extract stated intent from commit messages and the PR body.
3. Explore the surrounding system: callers of changed functions (Grep), related tests, config/schema the change touches.
4. Apply the analysis lenses: change taxonomy (feature/fix/refactor/removal), removed-behavior audit (what no longer happens), cross-file impact, invariant/contract delta, design pressure (what alternative was rejected and why), test delta.
5. Group hunks into narrative themes ordered by importance — one theme per Part 2 card. A theme is a behavioral unit ("token refresh moved to interceptor"), never a file list.

Step 3: Build the Document

Read template.html from this skill's base directory. It carries the full design system (tokens, components, generic quiz/gate JS) — fill it, never restyle it. No emoji, no hand-drawn SVG icons, no external resources (CDN, webfonts, remote images). The output must stay a single self-contained HTML file.

Before writing anything else, clear the template's own scaffolding:

• Delete the authoring comment at the top of the file (explain-diff output template. Fill every {{PLACEHOLDER}}…). It is instructions for you, not content for the reader.
• Fill <title> — it names the browser tab. explain-diff: {한 줄 요약} ({대상}).
• Delete every REPEAT / FIGURE SLOT comment once its block is filled or dropped.
• Before writing the file, grep your output for {{ — a surviving placeholder means an unfilled slot.

Writing style

The reader skims first and reads second. Prose that runs on defeats both.

• One idea per sentence. Split any sentence carrying two clauses joined by "그런데", "때문에", "면서" into two.
• Three to four sentences per paragraph, max. Break on the turn in the argument, not at an arbitrary length. A <p class="prose"> that fills more than ~5 lines on screen needs splitting.
• Lede is 2-3 sentences, not one long one. State the problem, then the fix. Do not chain the whole causal story into a single sentence.
• Bold the load-bearing phrase in a paragraph (<b>), not whole clauses. If three things are bold, nothing is.
• Prefer a concrete subject over a nominalization: "호스트가 규칙을 못 읽어요" beats "규칙 조회가 실패해요".

Natural Korean (do not read like machine translation)

The document must read as if a Korean engineer wrote it, not as if English or a raw code term were transliterated. Translation-ese and coined 한자어 are the loudest "AI wrote this" tell — remove them.

• No em-dash or en-dash (—, –) anywhere in the output — not in titles, TOC descriptions, prose, hints, or quiz text. They are a machine-writing marker. Use a colon, parentheses, a comma, or split into two sentences. Write 옵션 1만 vs 옵션 1+2: 권장안과 근거, never 옵션 1만 vs 옵션 1+2 — 권장안과 근거.
• Do not coin stiff 한자어 that Koreans do not actually say. If a natural word or the plain English term reads better, use it. 접두 → 앞에 붙는 upstage/ 또는 그냥 prefix; 회귀 커밋 → 되돌린 커밋; 귀속 → ~때문에. When unsure, say it the way you would out loud.
• Keep a code/identifier term verbatim rather than force-translating it. providerId, llmProxyUse, prefix stay as-is; wrapping them in an awkward Korean coinage only adds noise.
• Read each title and takeaway aloud once. If it sounds like a translated caption, rewrite it plainer.

Section titles

All titles — the hero title included — are short noun phrases (개조식/명사형), not sentences. Match the built-in ones (배경, 구조 한눈에 보기, 주의해서 볼 지점). Aim for 12 Korean characters or fewer per theme title.

A title is not just a heading: it is reused verbatim inside the TOC and inside the quiz hint button ({title} 섹션 →). A sentence-shaped title like 한 번의 sweep으로 끝나지 않았어요 makes that button eat an entire line, and a long title wraps mid-word in the hero. Write sweep이 놓친 3곳 instead.

Structure is fixed at three parts:

Top + TOC. The hero title is a noun phrase naming the change topic, not an action sentence: write 모델명 prefix 버그와 수정 방향, not 모델명에 upstage/ 접두가 붙어 채팅이 막혔어요. Keep it to ~20 Korean characters so it holds one line; the lede (2-3 sentences) carries the what/why, so the title does not need to. Metabar: target, commit range, file count, +/- totals, date. Each TOC row's description is that section's one-line takeaway so reading only the TOC summarizes the whole change; keep it a short phrase, no dash. Keep the Part group headers.

Part 1 — 개요.

• 배경: the before-state and its cost, then what the change achieves. Behavior level, not file level.
• 구조 한눈에 보기: annotated directory tree of every touched path. Chips state what happened (정본으로 승격, 67줄 → 1줄, 삭제 (렌더러)), deleted files get strikethrough. No section-jump links on tree rows.
• Optional interactive figure: include ONLY when an interaction exists where the user's input changes the outcome — a scenario toggle, a state switch whose columns respond differently (e.g. a start-location toggle showing two agents' loading paths side by side). Never build a step-through that reveals already-visible content in order; if no outcome-changing interaction exists for this diff, omit the figure entirely.

Part 2 — 변경 사항. One card per theme from Step 2, ordered by importance:

• Prose explaining behavior meaning — what the reader must understand, not a line-by-line narration.
• Verbatim diff excerpts (12 lines max per block; elide the middle with …). Only the lines that carry the theme.
• Close every card with a 핵심 정리 takeaway card: one bold sentence to remember + 2-3 supporting bullets. This is the same visual language as quiz explanations — blue tinted card = "the thing to remember".

Part 3 — 이해 점검.

• 주의해서 볼 지점: risk rows with Watch/Critical badges. Attention pointers, never verdicts. If a risk deserves a verdict, tell the user to run a code review — do not deliver one here.
• Quiz (below).

Quiz Specification

Exactly 5 questions by default, medium-hard. Each question must test practitioner-critical understanding — something that would change how the reader reviews, merges, or maintains this code:

• behavior prediction ("if X happens, what does the system actually do now?")
• failure modes ("which path is still unprotected?")
• rejected alternatives ("why was Y not chosen?" — only when the record/PR states it)
• invariants ("what does the check actually guarantee, and what not?")
• future-maintainer scenarios ("six months later, someone does Z — what breaks?")

Trivia (line counts, file names, dates) is banned. Distractors must be plausible misconceptions: the old system's behavior, a wrong-layer attribution, a swapped condition — never obviously absurd fillers.

Mechanics (already implemented by the template JS — supply only content):

• Exactly one option per question has data-ok="true".
• data-hint points to the section to re-read and never reveals the answer.
• data-hint-href is that section's own id (#sec2, #risks, …) and data-hint-label its title — together they turn the hint into a one-click jump, so the reader never scrolls back by hand. The id must exist in the document; the template drops the link if it does not resolve. Omit both only when no single section covers the question.
• Wrong answer → hint + retry (that question only); correct → explanation + lock.
• Explanation card: one bold core fact + bullets, including why the tempting wrong answer is wrong.
• The bottom gate opens only at 5/5. Its wording states understanding — never a fake action the page cannot perform (no "PR 보내기" buttons).

Step 4: Output

1. Write the file to the repository root: explain-diff-<slug>.html (slug from the change topic, kebab-case).
2. Report the absolute path to the user. Do NOT auto-open it, do NOT commit it, do NOT add it to .gitignore. Delete it only when the user asks.
3. Content language follows the project's AGENTS.md (or CLAUDE.md as fallback) language setting; if none, the user's conversational language. Korean output uses 해요체 throughout (headings may stay nominal).

Constraints:

• This skill is read-only with respect to git state — it creates exactly one HTML file and nothing else.
• Design decisions are fixed by the template and the design-system record (docs/decisions/2026-07-explain-diff-design-system.md in the git-claw repo). Do not improvise styles.