/explain-diff

name: explain-diff
description: >
  USE WHEN about to open a PR, when teammate asks "what's in this
  diff?", or when returning to a branch and needing self-orientation.
  Three modes: `--for pr|review|self`. Reads `git diff HEAD` (or
  passed range), returns 3–5 bullet plain-English narration.
  Read-only — defers security/test concerns to other skills.
allowed-tools:
  - Read
  - Bash(git diff:*)
  - Bash(git log:*)
  - Bash(git status:*)
  - Bash(git rev-parse:*)
argument-hint: "[ref-range, default HEAD] [--for pr|review|self]"

/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.

5. **Emit narration in the requested shape.**

`--for pr` output template

## Summary

- <one sentence per key change, ordered by importance>

## Why

<one paragraph: the motivation. If the diff doesn't make the motivation
obvious, say so explicitly — "motivation not inferable from the diff;
add to PR body".>

## How to verify

- [ ] <reviewer step 1>
- [ ] <reviewer step 2>
- <commands to run if applicable>

`--for review` output template

## What changed (load-bearing)

- `file:line` — <description of load-bearing change>
- ...

## What changed (mechanical, low-risk)

- <bulk list, less detail>

## What to look at first

<top 1–2 things the reviewer should NOT skip>

## What's untested

- <files modified without corresponding test changes, IF the language
  conventionally tests, IF the file is non-trivial>

## Load-bearing but un-anchored

- `file:line` — <the non-obvious decision that has no AIDEV anchor;
  suggest the anchor to add, e.g. "AIDEV-NOTE: retry order matters —
  webhook must land before the DB commit">
- <omit this section entirely if every load-bearing hunk is either
  self-evident or already anchored — don't manufacture findings>

`--for self` output template

- <bullet 1, ≤80 chars>
- <bullet 2>
- <bullet 3>
[max 5]

Hard rules

• **Read-only.** No Edit/Write in the tool list. If the user asks

"while you're at it, fix X" — STOP and surface that as a separate request.

• **Never invent intent.** If the diff doesn't make motivation

obvious, explicitly say "motivation not inferable from diff" rather than guess.

• **Never expand scope to security audit.** If sensitive paths show

up, ONE LINE: "diff touches `routes/auth/...` — consider `/security-review`". Don't try to be that skill.

• **Always cite file:line** for load-bearing claims.
• **Skip noise.** Don't list every renamed file individually if there

are 30 of them; aggregate ("renamed 30 files from `services/old/*` to `services/new/*`").

When to run

• Before opening a PR — paste the `--for pr` output into the PR body.
• After receiving a code review request from a teammate, run

`--for review` to make sure the diff is honestly readable.

• Coming back to a branch after a few days — `--for self` to

re-orient.

What this skill does NOT do

• **Generate the commit message.** That's the vanilla commit workflow.

They're different shapes: a commit message is per-commit; a PR description is per-branch. Don't conflate.

• **Audit for security/correctness.** Cite when sensitive paths

a