Tech Debt Skill

tech-debt-audit

A Claude Code skill that produces a thorough, citable tech debt audit of your entire codebase — not a generic best-practices checklist.

/tech-debt-audit

That's the whole interface. Run it in any repo, get back `TECH_DEBT_AUDIT.md` with file-cited findings, severity, effort estimates, and a ranked list of what to actually fix.

Why this exists

LLM-generated code reviews fail in a predictable way: they pattern-match against generic heuristics, surface obvious findings without grounding them in the actual code, and produce comprehensive-feeling output that nobody acts on. The result is a tab nobody opens twice.

This skill is opinionated about avoiding that failure mode. Three design choices do most of the work:

**Forced orientation before judgment.** The protocol requires the model to read the manifest, map the directory structure, analyze git churn, and write a mental model of the architecture *before* it forms any opinions. Phase 1 isn't optional. Findings without context are vibes.

**File:line citations on every finding.** A finding without a citation is unfalsifiable, and unfalsifiable findings don't get fixed. The skill rejects vague claims like "the code generally..." and requires `path/to/file.ext:LINE` on every concrete finding.

**A required "looks bad but is actually fine" section.** This is the single biggest separator between a real audit and a checklist regurgitation. Forcing the model to surface calls it considered making and chose not to is what catches shallow analysis. If that section comes back empty, the audit didn't look hard enough.

The skill also explicitly forbids recommending rewrites, forbids padding categories with filler, and produces a persistent artifact (`TECH_DEBT_AUDIT.md`) you can commit and track over time.

Why not the built-in Claude Code skills?

Claude Code ships several skills that touch this space. None of them do what a debt audit needs to do.

| Built-in | What it does | Why it's not a de