tech-debt-skill

What this skill does

```markdown
---
name: tech-debt-skill
description: Claude Code skill that produces a thorough, file-cited tech debt audit of an entire codebase across nine dimensions with severity ratings, effort estimates, and a ranked action list
triggers:
  - run a tech debt audit on this codebase
  - audit the technical debt in this project
  - find tech debt and code quality issues
  - generate a TECH_DEBT_AUDIT.md file
  - analyze codebase for architectural decay and code rot
  - what are the biggest tech debt problems in this repo
  - do a thorough code quality review with file citations
  - help me understand what needs refactoring in this project
---

# tech-debt-audit

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A Claude Code skill that runs a structured, three-phase tech debt audit across an entire codebase and writes `TECH_DEBT_AUDIT.md` — a persistent, file-cited, severity-ranked artifact you can commit and track over time.

## What it does

The skill sweeps nine debt dimensions:

1. **Architectural decay** — god classes, spaghetti dependencies, layer violations
2. **Consistency rot** — mixed patterns, style drift, naming inconsistencies
3. **Type & contract debt** — `any`, untyped interfaces, implicit nulls, broken contracts
4. **Test debt** — coverage gaps, brittle tests, untested critical paths
5. **Dependency & config debt** — outdated deps, unused deps, config duplication
6. **Performance & resource hygiene** — N+1 queries, unbounded growth, leaked resources
7. **Error handling & observability** — swallowed errors, missing logging, silent failures
8. **Security hygiene** — hardcoded secrets, injection patterns, weak crypto
9. **Documentation drift** — stale comments, missing docstrings, lying READMEs

Every finding is cited as `path/to/file.ext:LINE`. Every finding has severity (`Critical / High / Medium / Low`) and effort (`XS / S / M / L / XL`). The report includes a "things that look bad but are actually fine" section — the single biggest quality signal in any audit.

## Installation

**Personal install** (available in all your projects):

```bash
mkdir -p ~/.claude/skills/tech-debt-audit
curl -o ~/.claude/skills/tech-debt-audit/SKILL.md \
  https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md
```

**Project-only install** (just this repo):

```bash
mkdir -p .claude/skills/tech-debt-audit
curl -o .claude/skills/tech-debt-audit/SKILL.md \
  https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md
```

**Verify installation:**

```bash
claude --print "/skills" | grep tech-debt-audit
```

## Usage

### Basic audit

In Claude Code, in the repo root:

```
/tech-debt-audit
```

Output: `TECH_DEBT_AUDIT.md` in the repo root. First run: 5–20 minutes depending on repo size.

### Audit a subtree (monorepos)

```
/tech-debt-audit src/payments
```

Scopes the entire three-phase protocol to `src/payments/` only. Useful for large monorepos or targeted investigations.

### Mid-audit course correction

Interrupt after Phase 1 completes with:

```
Before Phase 2, tell me what surprised you in Phase 1 and what you
want to investigate that isn't in the dimensions list.
```

The best findings often come from things the prompt didn't anticipate.

### Repeat runs (living document mode)

On subsequent runs the skill reads the existing `TECH_DEBT_AUDIT.md` as a baseline:

- Resolved findings → marked `RESOLVED`
- Stale findings → updated in place
- New findings → tagged `NEW`

Just run `/tech-debt-audit` again. No flags needed.

## How it works (three phases)

### Phase 1 — Orient

The skill reads the manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.), maps the directory structure, analyzes `git log` for churn, identifies the largest and most-modified files (their intersection is where debt usually hides), then writes an internal mental model of the architecture before forming any opinions.

**Phase 1 is not optional.** Findings without context are vibes.

### Phase 2 — Audit

Sweeps all nine dimensions using `rg`, `ast-grep`, and language-native tooling:

| Stack | Tools run |
|-------|-----------|
| TypeScript / JavaScript | `npm audit`, `knip`, `madge`, `depcheck` |
| Python | `pip-audit`, `ruff`, `vulture`, `pydeps` |
| Rust | `cargo audit`, `cargo udeps`, `cargo machete` |
| Go | `govulncheck`, `staticcheck`, `golangci-lint` |

Tool output is folded into the findings table with citations. For repos over ~50k LOC, subagents are dispatched per module to avoid context exhaustion.

### Phase 3 — Deliverable

Writes `TECH_DEBT_AUDIT.md` with:

- Executive summary (finding counts by severity, debt concentration by path)
- Mental model of the architecture
- Full findings table with `file:line`, severity, effort, description, recommendation
- Top 5 priorities with rationale
- Quick wins checklist
- "Things that look bad but are actually fine" section
- Open questions for the maintainer

## Output format

```markdown
## Executive summary
- 3 Critical findings, 12 High, 31 Medium, 18 Low
- Largest debt concentration: src/payments/* (3 of 3 Critical findings)
- Estimated remediation effort for Critical+High: ~6 engineer-weeks

## Mental model
src/payments/ is the core revenue path. processor.ts has grown
to own routing, validation, retry, and reconciliation — functions
that arrived incrementally and were never extracted...

## Findings

| ID   | Category            | File:Line                      | Severity | Effort | Description                                              | Recommendation                                          |
|------|---------------------|-------------------------------|----------|--------|----------------------------------------------------------|---------------------------------------------------------|
| F001 | Architectural decay | src/payments/processor.ts:1240 | Critical | L      | 1,400-line god class: routing, validation, retry, recon | Extract retry + reconciliation into separate services   |
| F002 | Type & contract     | src/api/handlers.ts:88         | High     | S      | `req.body` typed as `any`, propagates to 6 call sites   | Add zod schema at boundary; infer type downstream       |
| ...  |                     |                               |          |        |                                                          |                                                         |

## Top 5

1. **F001** — Decompose `payments/processor.ts`: the retry and reconciliation
   logic has different failure modes and deployment cadence than routing.
   Extracting them reduces blast radius for the most-changed file in the repo.

2. ...

## Quick wins

- [ ] F042: Remove unused dep `lodash.merge` (replaced by native `structuredClone` at src/utils/clone.ts:14)
- [ ] F039: Delete commented-out feature flag block at src/flags/beta.ts:201–247 (flag shipped in v2.3)
- [ ] ...

## Things that look bad but are actually fine

- The deeply nested callback chain in `src/legacy/webhooks.ts:88–140` looks
  like a refactor target, but it preserves strict ordering guarantees the
  queue-based replacement would silently break. Leave it.
- `src/db/migrations/` has zero test coverage. This is intentional — the
  migration runner validates checksums before applying; tests would duplicate
  that guarantee without adding signal.

## Open questions for the maintainer

- Is `src/experiments/` intentionally untested, or did it fall through coverage?
- `config/staging.yml` and `config/production.yml` are 94% identical. Is there
  a plan to merge them, or is the divergence load-bearing?
```

## Customization

### Add domain-specific dimensions

Fork `SKILL.md` and add dimensions to the Phase 2 sweep. Examples:

- **Frontend repos** → accessibility debt (missing ARIA, contrast violations)
- **ML repos** → eval drift (model versions pinned to stale benchmarks)
- **LLM apps** → prompt versioning debt, tool-call cost regressions
- **Infra repos** → IaC drift (resources that exist in cloud but