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.2.1"},
  "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": []
  }
}