explain-metrics

name	explain-metrics
description	Use this skill when the user asks what a claude-code-complexity-guard metric (CCS, HSI, DR) means, why their edit was blocked, what cognitive complexity is, what helper sprawl is, or how to interpret a violation report. Triggers on "what is CCS", "explain helper sprawl", "why did the complexity guard block my edit", "what does CCS 37 mean", "how does displacement ratio work".

Explain Metrics

claude-code-complexity-guard ships two enforced metrics in V1 (CCS and HSI) and one Phase-2.5 metric (DR, advisory-only until DR's full computation chain lands). This skill explains each one and how the hooks decide whether to block or warn.

CCS — Cognitive Complexity Score

CCS measures how mentally taxing one function is to follow. The implementation is Campbell 2018 cognitive complexity (the SonarSource metric) — see docs/metric-vocabulary.md for the formula.

Increment rules:

• B1 — flat +1, no nesting penalty: else / elif-equivalent; the first occurrence of a homogeneous boolean operator chain (a && b && c adds +1, not +3); switching operators in a chain (a && b || c adds 2).
• B2 — +1 plus current nesting depth: if, for, while, loop, match/switch, ternary, catch / except (the catch IS B2; the try block per se is not). Closures fire B2 AND reset nesting depth to 0 for the closure body.
• B3 — flat +1: labeled break / continue (Python has no labels — B3 dormant).

Default thresholds (from the default preset):

• Existing functions: per_function: 30
• Newly-added functions: new_function: 20

These are 2x and 1.33x the SonarSource cross-language consensus default (15). The strict preset halves the headroom (20 / 15) to enforce the consensus directly. The advisory preset uses the same numbers as default but with block: false everywhere — warnings only.

HSI — Helper Sprawl Index

HSI measures how many private single-caller helper functions a patch introduces, normalised by patch size:

HSI = (count of new private single-caller helpers) / patch_LOC

A "single-caller helper" is a private function whose call edges in the same file show exactly one caller (excluding self-recursion, compared on qualified names so Foo::helper calling Bar::helper counts as a real call, not self-recursion).

Default threshold (from default preset): 0.01 — at most 1 single-caller helper per 100 LoC of patch. The strict preset halves this to 0.005.

Why this matters: extracting helpers used in only one place is a common signal of agentic "fake refactor" — per-function CCS drops, but module-level helper count rises with no real reduction in complexity. HSI catches this before it lands.

DR — Displacement Ratio (Phase 2.5; not yet enforced)

DR measures whether a refactor reduced complexity locally or just displaced it elsewhere — into the public API surface or shared state. The formula (locked for Phase 2.5):

displacement_growth = max(0, Δapi)         + max(0, Δstate)
local_reduction     = max(0, -Δlocal_cognitive)

           displacement_growth − local_reduction
DR =  ────────────────────────────────────────────────
       max(1, displacement_growth + local_reduction)

DR ∈ [-1, 1]. DR > 0 means displacement detected: more complexity flowed into public API or shared state than was reduced locally.

V1 ships with DR enabled: false in every preset's effective state — the schema reserves the field but the runtime ignores it until Phase 2.5 lands the full computation chain (touched-file ledger, rename resolution, cargo public-api diff, computability gate, PreToolUse per-file baseline blob).

Why was my edit blocked?

A PostToolUse block (exit code 2) means a metric whose policy is block: true exceeded its threshold. Inspect the violation entry:

{
  "metric": "CCS",
  "function": "classify",
  "value": 37,
  "threshold": 30,
  "location": "src/foo.rs:42"
}

The value is the function's score; threshold is what the active preset allows. To resolve:

1. Look at the function at location and reduce the cognitive complexity (flatten nested control flow, extract guard clauses, or split the function along its discrete responsibilities).
2. If the threshold is wrong for your codebase, adjust via .cogcomp.yml overrides — see configure-budget skill.

How to opt into a different preset

Run /claude-code-complexity-guard:configure-budget to write or update .cogcomp.yml. Available presets:

• off — every metric disabled.
• advisory — warning-only mode at default thresholds (V1 release default).
• default — block at default thresholds (CCS 30/20, HSI 0.01).
• strict — block at tighter thresholds (CCS 20/15, HSI 0.005).

You can also override individual fields, e.g.:

preset: default
overrides:
  ccs:
    per_function: 40
    block: false