code-debt

What this skill does

# Code Debt

Surface code-level debt and understand what it's costing the project.

## Philosophy

> "What does our code still owe us that we haven't paid?"

Every TODO is a promise. Every deprecated call is a migration the team chose to defer. Every commented-out block is a decision someone hasn't made. Code-debt names those debts so the team can decide which to pay.

Not a linter. A linter asks "does this match a rule?" This skill asks "what have we left unfinished, and what's it costing us?"

## Scope

The user may specify a file path, glob pattern, or directory. If not specified, ask: *"Which path or module would you like to analyze?"*

## Config Integration

Follow the migration preflight in `references/config-migration.md`.

After preflight, read `.assistant-config.md` for:
- **Debt Scope** overrides (`code-debt.max-function-lines`, etc.)
- **Acknowledged Debt** entries for this dimension (skip these)
- **Architecture Principles** (optional context for judgment)

If no config exists, use heuristic defaults from `references/code-debt-patterns.md`.

## Stack Detection

Glob for manifest files to infer language conventions:
- `package.json` → JavaScript/TypeScript
- `pyproject.toml` / `requirements.txt` → Python
- `Gemfile` → Ruby
- `go.mod` → Go
- `Cargo.toml` → Rust

Show detected stack in the output header. If unclear, proceed with language-agnostic patterns only.

## Process

### 1. Understand context

Read a representative file or two from the scope to understand the codebase's style. Note whether the project already tracks debt in comments (e.g. `TODO(#1234)` with issue refs) — those are tracked items, not untracked debt.

### 2. Scan

Use Grep for each pattern category. See `references/code-debt-patterns.md` for the full list. Collect raw findings with `file:line` locations.

For **rename/identifier drift**, scan the whole project tree — not just source. Config files, `.gitignore`, agent definitions, CI configs, and docs commonly hold the old name after a source-only rename. The point of this check is the blast radius.

### 3. Group by location

Organize findings by module/directory, not by pattern type. A file with a TODO, a deprecated import, and a magic number is one location with three findings — not three scattered items.

### 4. Assess impact

For each location group, judge:
- **Impact** (H/M/L): does this debt block changes, risk bugs, or just offend taste?
- **Effort** (S/M/L): roughly how much work to pay it down?
- **Priority** (P2/P3/P4): feed into triage via `/triage`.

## Reference

- `references/code-debt-patterns.md` — what counts, what doesn't
- `references/debt-output-format.md` — required output format
- `references/config-migration.md` — config migration preflight

## Output format

Follow `references/debt-output-format.md` exactly. The umbrella skill parses this format.

## What Makes This Different From a Linter

A linter would flag every TODO as noise. This skill:

1. Sees patterns — one tracked TODO vs. ten untracked ones in the same file
2. Assesses impact — a magic number in a config is different from one in an auth check
3. Groups by location — three debts in one module is a hotspot, not three separate items
4. Produces triage-ready output — each location comes with suggested impact/effort/priority, ready for `/triage` or pasting into a tracker

The value is **judgment**, not detection.