code-health

Code Health

Measure first; interpret second. The analyzer locates structural evidence and quantifies change. The agent then reads the implicated code to decide whether the structure is justified. A metric is never itself a defect.

This skill complements lint: lint owns mechanically decidable local defects, while code-health owns measured signals that require contextual judgment. It is not a quality gate and never emits an unhealthy verdict.

Invariants

1. Differential by default. Compare with the change's starting ref. Attribute only raw-value changes and new structural relationships to the change; retain whole-repository values as context. Use --all only for an explicit baseline audit.
2. Facts and judgment stay separate. The script emits facts, coverage, and bounded investigation candidates. The agent supplies interpretation and recommendations after inspecting the code.
3. Missing measurement is unavailable, never clean. Read the language-by-metric coverage matrix before interpreting results. Never compare measured Python functions with unmeasured functions in another language. Read repository.unrecognised_extensions too — a language absent from the extension table produces no coverage row, so that grouped extension-to-count map is the only evidence those files exist — and repository.coverage_limits for what the measurement could not reach.
4. No score or universal target. Do not convert comments-to-code, tests-to-code, duplication, complexity, or any composite into a repository grade. Ratios and ranks identify anomalies; they do not define quality.
5. Raw change, not percentile movement. A candidate must be supported by a changed raw value or new relationship. Population rank may order a bounded reading list but never establishes regression.
6. Git defines the default scope. Analyze tracked and untracked non-ignored files. Apply no hidden vendor/generated exclusions. Record every explicit configuration exclusion.
7. Successful analysis exits zero regardless of evidence. Exit 2 means an execution error; exit 3 means required coverage was unavailable or a differential scope was empty. No exit code means "unhealthy."
8. No installation at all. The portable floor requires only Python 3.13 and Git. Lizard is the optional multi-language complexity collector: detect reports whether it is present and names the command that would install it. The analyzer has no code path that installs anything, so widening coverage is always a human's explicit act outside this skill.