Diff Summary

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.