explain-diff

/explain-diff

What it does

Reads a git diff and produces a tight English narration of what changed, why a reviewer should care, and where the risk concentrates. Lives next to the vanilla commit workflow (mechanical Conventional Commits message) and /security-review (structured security audit) — covers the "narrative" niche neither does.

Three audience modes:

• --for pr (default) — output is a PR-description-shaped block: ## Summary, ## Why, ## How to verify. Copy-pasteable into the PR body.
• --for review — emphasizes what's load-bearing and what's mechanical; flags non-obvious decisions that the reviewer might miss without the author's voice ("the new IF EXISTS clause on line 47 is load-bearing — without it the migration is non-idempotent").
• --for self — terse 3–5 bullet self-narration; useful before switching context or coming back to a branch later.

Workflow

1. Resolve diff range.

   • Default: git diff HEAD (working tree + staged vs last commit).
   • If $ARGUMENTS starts with ^ or contains .. or ..., treat as a ref range and use git diff <range>.
   • If --for pr and the current branch has commits beyond main, use git diff main...HEAD instead (covers the whole branch).

2. Get supporting context (parallel-OK):

   • git status --short for file-state breakdown.
   • git log --oneline -10 for repo style of commit messages.
   • git rev-parse --abbrev-ref HEAD for branch name.

3. Read the diff in full. If the diff is enormous (>50k tokens estimated), STOP and report: "diff is too large — narrow with --paths <pattern> or <file>...". Don't try to chunk and summarize partial diffs; the result would be incoherent.

4. Walk the diff and identify:

   • Files added vs modified vs deleted.
   • Hunks that look mechanical (renames, type-only changes, formatting).
   • Hunks that look load-bearing (new branches, new functions, condition changes, new dependencies).
   • Test changes (file paths matching *_test.*, *.test.*, tests/, etc.).
   • Doc / config-only changes.
   • Anything that touches a sensitive path (auth*, crypto*, *.env*, routes/, etc.) — surface as a "consider /security-review" reminder, not a substitute for it.
   • Load-bearing decisions shipped without an AIDEV- anchor (only in --for review). A load-bearing hunk that encodes a non-obvious choice — an ordering dependency, a perf carve-out, an idempotency trick, a deliberate rejection of the obvious approach — and carries no AIDEV-NOTE: / AIDEV-TODO: / AIDEV-QUESTION: in the added lines is a memory the next agent won't inherit. This is the review-boundary backstop for the ai-first-nudge hook, which only fires on ≥50-LOC single writes and so misses decisions built up incrementally.