code-health

---
name: code-health
description: >
  Use when the user asks about code health, code quality, complexity, technical debt, which files
  are risky or hard to maintain, what to refactor next, untested hotspots, or coverage gaps in a
  Repowise-indexed codebase (.repowise/ directory exists). Also use to get a before/after health
  read when planning or finishing a refactor.
user-invocable: false
---

# Code Health with Repowise

Repowise scores **every file 1–10** from deterministic markers — McCabe
complexity, deep nesting, brain methods, class cohesion (LCOM4), god classes,
clone detection, untested hotspots, function-level churn, ownership dispersion,
and more. Zero LLM calls; pure local analysis. The weights are calibrated
against a real defect corpus, so a low score means *more likely to harbour bugs*,
not just *bigger*.

## Pick the mode by what you pass

- **Dashboard**: `get_health()` (no targets): `fix_first`, the ranked list of
  what to fix first, then repo-level KPIs and the lowest-scoring files. Start here for "how
  healthy is this codebase?" or "what should we clean up?".
- **Targeted** — `get_health(targets=["src/x.py", "src/y.py"])`: per-file score
  and the specific marker findings driving it. Use before/after a refactor,
  or to explain *why* a file is flagged.

## Useful `include` flags

`get_health(targets=[...], include=[...])`:
- `"biomarkers"` — always return the findings list (what's wrong, where).
- `"refactoring"` — deterministic, ranked refactoring suggestions (by impact/effort).
- `"coverage"` — surface coverage data when it's been ingested.
- `"trend"` — recent health snapshots + declining / predicted-decline signal.

`include` adds blocks; `only=[...]` subtracts them.

## How to use the results

1. For "what should I refactor?" → dashboard mode, lead with `fix_first`; open
   an item with `get_health(fix_id=...)` for its steps and the tests to run,
   and present the plan, not just the scores.
2. Rank by `weighted_deficit`, not `score` — the score floors at 1.0.
3. For a specific file → report the score, the top 2–3 marker findings, and
   what each one means in plain language. Avoid dumping the raw payload.
4. Check `unresolved` before calling a file clean: a target listed there matched
   nothing, and `not_indexed` means run `repowise update`.
5. Before editing a flagged file → cross-check `get_risk(targets=[...])`; a file
   that is both low-health *and* a churn hotspot deserves the most care.
6. Untested-hotspot / coverage questions → tell the user coverage markers
   light up once they ingest a report: `repowise coverage add cov.lcov`
   (LCOV / Cobertura / Clover; a coverage.py `.coverage` also builds the
   per-test map), then `repowise health --recompute` to fold it into the scores.

## CLI equivalents

- `repowise health` — KPIs + lowest-scoring files
- `repowise health --refactoring-targets` — ranked by impact / effort
- `repowise health --trend` — snapshots + declining alerts
- `repowise coverage add <file>` — ingest coverage, light up untested-hotspot

## Error handling

If `get_health` reports no repository, suggest `/repowise:init`. Code health is
computed even with a template-rendered wiki (no LLM needed), so it should be available
whenever the repo is indexed.