diff-summary
Structured triage of a git diff. One call replaces the per-file Read sweep an agent normally does to figure out which files in a diff are tests, which touch the public API, which are migrations, which need careful review.
Lives at ${CLAUDE_SKILL_DIR}/../../bin/diff-summary; the plugin auto-adds bin/ to PATH, so just run diff-summary ....
When to reach for this
- User asks "what changed in this branch / triage this PR / is this safe to merge" → run
diff-summary --base main --pretty. Read the summary.highRiskFiles and summary.byRole first; only Read individual files where risk is HIGH.
- User asks "what am I about to commit" → run
diff-summary --pretty (default = working tree) or diff-summary --staged --pretty after a git add.
- Pre-PR sanity check →
diff-summary --base main --risk medium --pretty shows only the files that need a second look.
- "Did I forget to update the tests?" → check
summary.sourceFilesWithoutTestChanges.
Headline command
diff-summary # working tree (default)
diff-summary --staged # staged index
diff-summary --base main # <base>...HEAD (3-dot merge-base)
diff-summary --range A..B # explicit range, passed verbatim
diff-summary --max-files 200 # cap files[] (default 200)
diff-summary --include-patches # include raw unified diff per file (opt-in)
diff-summary --public-api-only # filter files[] to publicApiTouched only
diff-summary --risk medium # filter files[] to risk >= MIN
diff-summary --output /tmp/d.json --shape-depth 2 # offload large payload
diff-summary --pretty # indented JSON
The four diff-source flags (--staged, --base, --range, default) are mutually exclusive.
Output shape (truncated)
{
"tool": {"name": "diff-summary", "version": "0.1.0"},
"mode": "base",
"base": "main",
"head": "abc1234",
"branch": "feature/foo",
"summarizedAt": "2026-04-28T12:34:56Z",
"stats": {"files": 12, "insertions": 234, "deletions": 67, "movedLinesEstimate": 18},
"files": [
{
"path": "src/foo.ts",
"status": "modified",
"role": "source",
"language": "typescript",
"insertions": 42, "deletions": 5,
"binary": false,
"publicApiTouched": true,
"risk": "high",
"riskReasons": ["touches-public-api", "no-test-changes"]
}
],
"summary": {
"byRole": {"source": 5, "test": 3, "config": 2, "doc": 1, "generated": 1},
"highRiskFiles": ["src/foo.ts"],
"testFilesTouched": 3,
"sourceFilesWithoutTestChanges": ["src/bar.ts"],
"publicApiTouches": ["src/foo.ts"],
"migrationsTouched": [],
"secretsRiskFiles": []
}
}
Stay in your lane
- Reading file contents → use the Read tool.
diff-summary is the structural picture; for the actual changed code, Read the file.
- Deeper logical / security review → use a code-reviewer skill or sub-agent. This tool flags risk paths; it does not analyze whether the logic is correct.
- Coverage analysis → out of scope. We flag "no co-changed test in this diff", which is not the same as "this code has no test coverage anywhere."
- Secret scanning → out of scope. We flag SECRET-RISK PATHS (
.env*, *.pem, *.key, id_rsa*, secrets.*) so you can prompt the user, but we do not read or scan file contents. Use git-secrets or detect-secrets for real secret scanning.
- Symbol indexing / "where is
myFunction defined" → not this tool.
Honest limits
- Public-API detection is heuristic — it looks for
+export , +pub fn, +func [A-Z], +def <name>(, plus well-known entrypoint paths (index.{ts,tsx,js}, mod.rs, lib.rs, __init__.py, main.go). It will miss public-API touches in unusual file layouts and over-flag in test fixtures named index.ts.
- Risk tiers are advisory, not deterministic. They guide where to look first.
- Co-changed-test detection is name-stem-based; refactors that move tests across directories will trip it. Prefer false-positive (no test detected when there is one) over false-negative.
- Moved-lines estimate is naive whitespace-trimmed line matching across files — useful for "is this a refactor?" but not authoritative.
- Without
--include-patches, only stats + classification ship. With it, the raw unified diff per file is included — payload size grows quickly; offload with --output for large diffs.
1---2name: diff-summary3description: One-call structured triage of a git diff. Returns per-file role classification (source/test/config/doc/generated/build/fixture/migration), risk tier (low/medium/high) with reasons, public-API touch detection, co-changed-test detection, secret-risk path flagging, and aggregate stats. Replaces the 5-20 Read calls an agent burns reading each modified file individually to figure out "what kind of change is this and how risky is it". Stateless, no network, stdlib Python only.4when_to_use: Trigger on "what changed in this branch", "triage this PR", "summarize the diff", "is this PR safe to merge", "what's risky about this change", "what did I touch", pre-commit / pre-PR sanity checks, code-review preparation. Use BEFORE reading individual modified files — the structural picture answers most "what kind of PR is this" questions without reading any file content.5allowed-tools: Bash(diff-summary:*) Bash(python3 *diff-summary*:*)6metadata:7 source: https://skillmd.com/skills/aibot88/diff-summary8---910# diff-summary1112Structured triage of a git diff. One call replaces the per-file Read sweep an agent normally does to figure out which files in a diff are tests, which touch the public API, which are migrations, which need careful review.1314Lives at `${CLAUDE_SKILL_DIR}/../../bin/diff-summary`; the plugin auto-adds `bin/` to PATH, so just run `diff-summary ...`.1516## When to reach for this1718- User asks **"what changed in this branch / triage this PR / is this safe to merge"** → run `diff-summary --base main --pretty`. Read the `summary.highRiskFiles` and `summary.byRole` first; only Read individual files where risk is HIGH.19- User asks **"what am I about to commit"** → run `diff-summary --pretty` (default = working tree) or `diff-summary --staged --pretty` after a `git add`.20- Pre-PR sanity check → `diff-summary --base main --risk medium --pretty` shows only the files that need a second look.21- "Did I forget to update the tests?" → check `summary.sourceFilesWithoutTestChanges`.2223## Headline command2425```bash26diff-summary # working tree (default)27diff-summary --staged # staged index28diff-summary --base main # <base>...HEAD (3-dot merge-base)29diff-summary --range A..B # explicit range, passed verbatim3031diff-summary --max-files 200 # cap files[] (default 200)32diff-summary --include-patches # include raw unified diff per file (opt-in)33diff-summary --public-api-only # filter files[] to publicApiTouched only34diff-summary --risk medium # filter files[] to risk >= MIN35diff-summary --output /tmp/d.json --shape-depth 2 # offload large payload36diff-summary --pretty # indented JSON37```3839The four diff-source flags (`--staged`, `--base`, `--range`, default) are mutually exclusive.4041## Output shape (truncated)4243```json44{45 "tool": {"name": "diff-summary", "version": "0.1.0"},46 "mode": "base",47 "base": "main",48 "head": "abc1234",49 "branch": "feature/foo",50 "summarizedAt": "2026-04-28T12:34:56Z",51 "stats": {"files": 12, "insertions": 234, "deletions": 67, "movedLinesEstimate": 18},52 "files": [53 {54 "path": "src/foo.ts",55 "status": "modified",56 "role": "source",57 "language": "typescript",58 "insertions": 42, "deletions": 5,59 "binary": false,60 "publicApiTouched": true,61 "risk": "high",62 "riskReasons": ["touches-public-api", "no-test-changes"]63 }64 ],65 "summary": {66 "byRole": {"source": 5, "test": 3, "config": 2, "doc": 1, "generated": 1},67 "highRiskFiles": ["src/foo.ts"],68 "testFilesTouched": 3,69 "sourceFilesWithoutTestChanges": ["src/bar.ts"],70 "publicApiTouches": ["src/foo.ts"],71 "migrationsTouched": [],72 "secretsRiskFiles": []73 }74}75```7677## Stay in your lane7879- **Reading file contents** → use the Read tool. `diff-summary` is the structural picture; for the actual changed code, Read the file.80- **Deeper logical / security review** → use a code-reviewer skill or sub-agent. This tool flags risk paths; it does not analyze whether the logic is correct.81- **Coverage analysis** → out of scope. We flag "no co-changed test in this diff", which is not the same as "this code has no test coverage anywhere."82- **Secret scanning** → out of scope. We flag SECRET-RISK PATHS (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `secrets.*`) so you can prompt the user, but we do not read or scan file contents. Use git-secrets or detect-secrets for real secret scanning.83- **Symbol indexing / "where is `myFunction` defined"** → not this tool.8485## Honest limits8687- Public-API detection is heuristic — it looks for `+export `, `+pub fn`, `+func [A-Z]`, `+def <name>(`, plus well-known entrypoint paths (`index.{ts,tsx,js}`, `mod.rs`, `lib.rs`, `__init__.py`, `main.go`). It will miss public-API touches in unusual file layouts and over-flag in test fixtures named `index.ts`.88- Risk tiers are advisory, not deterministic. They guide where to look first.89- Co-changed-test detection is name-stem-based; refactors that move tests across directories will trip it. Prefer false-positive (no test detected when there is one) over false-negative.90- Moved-lines estimate is naive whitespace-trimmed line matching across files — useful for "is this a refactor?" but not authoritative.91- Without `--include-patches`, only stats + classification ship. With it, the raw unified diff per file is included — payload size grows quickly; offload with `--output` for large diffs.