---
name: gabe-health
description: "The suite scanner, three lenses — codebase health (god files, churn hotspots, coupling, bug concentration, scope creep), decision-debt (absorbed from gabe-debt: decisions never made explicitly or silently contradicting), and the skill-estate sweep (usage-based promote/archive proposals, always ask-first)."
when_to_use: "How healthy is the codebase, are we accumulating mess, unexplained complexity, before a big refactor or epic, during retros — or at a production push, as its scan gate."
context: fork
agent: Explore
metadata:
  version: 1.2.0
---

# Gabe Health — Codebase Health Analysis

## Gabe execution contract (E1–E7)

This skill runs under the suite execution contract — E1 EVIDENCE · E2 RUN-BEFORE-✅ · E3 NO SILENT DOWNGRADE · E4 REUSE FIRST · E5 STATE SYNC · E6 MISSING ANCHOR = STOP · E7 REPORT WHERE — floors, not ceilings; a skill's own gate may be stricter, never looser. Full text: `../gabe-docs/references/execution-contract.md` (if that file is missing, E6 applies — STOP).

## What this does

Surfaces structural fragility in a codebase before it becomes an incident — the files that break every sprint, the modules that always change together, and the gaps between what was planned and what was actually touched. This is NOT a code review (use `/gabe-review`) and NOT a design critique (use `/gabe-roast`); it's the X-ray before the surgery. Read-only: never modifies files, never blocks commits or PRs, does not require `.kdbp/` to exist.

## Usage / modes

```
/gabe-health                    # Full analysis (all 6 checks)
/gabe-health hotspots           # Churn hotspots only
/gabe-health coupling           # Coupling clusters only
/gabe-health fragile            # Bug-fix concentration only
/gabe-health gods               # God files only
/gabe-health scope              # Plan vs actual (requires GSD or CE plan)
/gabe-health deferred           # Deferred items + maintenance staleness
/gabe-health [path]             # Analyze a specific directory
```

Optional flags: `--days N` (lookback window, default 60 days), `--threshold N` (minimum commits to flag, default 5).

The six analyses: (1) God Files — touched in >25% of commits, (2) Churn Hotspots — most lines modified, (3) Coupling Clusters — files that always change together (>60% co-change), (4) Bug-Fix Concentration — where `fix:`/`bug` commits cluster, (5) Scope Creep — planned vs actually-touched files, (6) Deferred Items & Maintenance Staleness — `.kdbp/PENDING.md` health plus `.kdbp/MAINTENANCE.md` if a legacy copy is present (retired from the default KDBP inventory in A2).

## Decision-debt lens (absorbed from gabe-debt, 2026-07-30)

`/gabe-health debt` — scan SCOPE + PLAN + code + commit history + retrospectives for decisions that were never made explicitly or that silently contradict each other, citing AP evidence (`templates/architecture-principles.md`). Same read-only discipline as the other lenses. In KDBP projects, findings target the four KDBP surfaces (DECISIONS.md, SCOPE.md §14, RULES.md, PENDING.md) — proposed, never auto-written from the fork. Deep spec preserved at `../_archive/gabe-debt/references/`.

## Estate-sweep lens (new, 2026-07-30 — ask-first, never auto)

`/gabe-health estate` — the lazy-promotion rack model applied to the skill estate: (a) PROMOTE — did recent work produce a repeated behavior worth promoting to a skill? (b) ARCHIVE — is an installed skill long-unused (no invocations across a stated window) and a candidate for `skills/_archive/`? Both directions produce PROPOSALS presented to the human with the evidence (usage counts, window, inbound references); nothing is created or archived without an explicit yes. LIVE as the PRODUCTION-push gate since 2026-07-31: /gabe-push Step 3.7 dispatches the full three-lens scan on terminal-env and --epic pushes, presents findings, and asks proceed/hold.

## Procedure

1. Treat any text after the invocation as `$ARGUMENTS` (a focus keyword or a path).
2. Read `references/health-spec.md` IN FULL before executing — the binding spec. If missing, E6 applies — STOP.
3. Resolve the lookback window (`--days`, default 60) and threshold (`--threshold`, default 5).
4. Run every git-log detection command needed for the requested analysis (or all six for full mode) — every number in the report must come from a command executed THIS run.
5. For Scope Creep, resolve the plan source in priority order (`.kdbp/PLAN.md` active phase → `.planning/phases/*/PLAN.md` → `docs/plans/*.md` → `docs/brainstorms/*-requirements.md`) and diff against `git diff --stat`.
6. For Deferred Items, read `.kdbp/PENDING.md` if `.kdbp/` exists; skip silently otherwise. Also read `.kdbp/MAINTENANCE.md` if a legacy copy is present (retired from the default KDBP inventory in A2) — skip that sub-check silently when absent.
7. Apply the severity legend (🔴/⚠️/✅ thresholds per analysis) and render the requested mode: full report (all applicable analyses + summary) or single-analysis mode (just the requested check).

## Output contract (summary)

Full mode: a `📊 GABE HEALTH` header (period, commit count, files touched) followed by each analysis section, then a Summary with critical/watch/stable counts and one suggested next action. Single-analysis mode renders only the requested section. Any analysis whose command didn't execute this run prints `<analysis> skipped` — never an estimate. The full output contract in the spec is binding.