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: ```bash git d...