| name | audit-patch |
| description | Use this skill when the user wants to audit an arbitrary git rev-range (e.g. `HEAD~3`, `main`, a SHA) against the claude-code-complexity-guard CCS+HSI pipeline OUTSIDE a Claude session — for example, before opening a PR, after a manual refactor, or to inspect what a feature branch did. Triggers on "audit my branch", "check complexity since main", "run cogcomp on HEAD~3", "audit-patch", "complexity report for this rev range". Does NOT analyse `.patch` files or stdin diffs — for pre-commit-time staged-content analysis use the `audit-staged` CLI instead. |
Audit Patch
/claude-code-complexity-guard:audit-patch <git-rev> analyses the
delta between <git-rev> and HEAD against the same engine the
PostToolUse hook uses (CCS + HSI). It is the user-invoked entry point
for ad-hoc rev-range complexity reports — useful before opening a PR,
after a manual refactor, or to inspect what a feature branch did.
Usage
audit-patch <git-rev>
<git-rev> is anything git rev-parse <git-rev>^{commit} accepts: a
short SHA, a full SHA, a branch name (main, origin/main), a tag, or
a relative ref (HEAD~3, HEAD@{1}).
Examples:
audit-patch HEAD~3
audit-patch main
audit-patch v1.2.0
audit-patch a1b2c3d
What it does
- Race-free SHA pinning. Resolves both
<git-rev> and HEAD to
commit SHAs once at audit start. Every git invocation that
follows uses those resolved SHAs, so a concurrent git checkout or
git commit cannot shift the audit window mid-run.
- Rename-aware enumeration. Walks the rev-range delta via
git diff <rev_sha>..<head_sha> --name-status -z -M. Renames are
tracked through R<score> entries; the new path is analysed with
the old path's content used as the baseline. Copy detection (-C)
is intentionally NOT enabled — re-introducing it is a separate
future change gated on adoption evidence.
- Blob-only reads. Both baseline and current content are fetched
via
git show <sha>:<path>. The working tree is NEVER read, so
unstaged or staged edits do not contaminate the audit.
- Delta-aware violation rule. Only the rev-range delta produces
violations:
- A function present in current but absent in baseline (new
function) is judged against
ccs.new_function.
- A function whose CCS score increased between baseline and
current is judged against
ccs.per_function.
- Unchanged or improved functions are silently excluded — your
pre-existing complexity is not graded by
audit-patch.
- HSI counts only helpers introduced between baseline and current
and is normalised by the rev-range LoC delta.
Status table
| Status | Action |
|---|
A (added) | analyse new path; baseline=empty (every fn is new) |
M (modified) | analyse path; baseline=<rev>:<path>, current=<HEAD>:<path> |
T (type change) | treat as M |
R<score> (renamed) | analyse new path; baseline=<rev>:<old_path> |
D (deleted) | SKIP — no current content (informational stderr line) |
U (unmerged) | SKIP — resolve the conflict first (advisory stderr line) |
X (unknown) | SKIP — git emitted an unknown status (advisory stderr line) |
Skipped entries are surfaced on stderr; they never contribute to the
exit code.
Output
Stdout carries a human-readable report:
audit-patch: <rev_sha[:12]>..<head_sha[:12]> (preset: <name>)
files analysed: <n>; skipped: <m>
[<status> <path>] <n> violation(s) (<k> fn analysed)
- CCS [BLOCK|advisory] `<name>` at <path>:<line>: score X > threshold Y
- HSI [BLOCK|advisory] <path>: V > threshold T (H new helpers across L added LoC)
function CCS (top 5):
...
decision: pass | advisory | block
pass — no violations. advisory — one or more violations, but none
have block: true under the active .cogcomp.yml preset. block —
at least one blocking violation.
Exit codes
| Code | Meaning |
|---|
0 | Clean OR every entry was skipped / advisory-only |
1 | At least one blocking violation under the active preset |
2 | Bad input — rev unresolvable, missing arg, malformed git invocation, or .cogcomp.yml parse error |
What it does NOT do
- No
.patch file input. audit-patch does not parse unified
diffs from a file or stdin. Re-introducing those modes would
require either a unified-diff parser (~150–300 LOC for correctness
on rename / binary / mode-change / no-newline-at-eof edges) or a
shell-out to git apply --check against a temp tree — both real
architectural commitments deferred until adoption proves the need.
- No DR (Displacement Ratio). DR requires the per-file baseline
blob captured by the PreToolUse hook during a Claude session.
Rev-range audits are session-independent, so DR cannot be computed
here. CCS + HSI cover the rev-range case.
- No pre-commit gate.
audit-patch is a report tool. To enforce
complexity thresholds at commit time, use the audit-staged CLI
(Phase 4.3) — it analyses git diff --cached and exits non-zero on
blocking violations, which a pre-commit framework can wire up.
Workflow
- Decide a rev to audit against (
HEAD~3, main, origin/main, a
tag, a SHA).
- Run
audit-patch <rev> from anywhere inside the repo. The helper
resolves the repo root via git rev-parse --show-toplevel.
- Inspect the printed report. A
decision: block exit-1 means at
least one rev-range violation exceeds the active preset's
blocking threshold; address the listed functions or relax the
preset via configure-budget before merging.
- Skipped entries (
D / U / X) appear on stderr — review them
manually if the rev range moved files or had merge conflicts.
Related skills
configure-budget — change the preset / overrides that
audit-patch reads from .cogcomp.yml.explain-metrics — understand what CCS / HSI mean and how
thresholds are set.
