# Tech Debt Audit

Thorough, user-invoked tech debt and architecture audit of the current codebase.

- Repository: https://github.com/ksimback/tech-debt-skill (626 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-04-25
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ksimback/tech-debt-skill --skill tech-debt-audit -g -a claude-code -y`
Codex: `npx skills add ksimback/tech-debt-skill --skill tech-debt-audit -g -a codex -y`
Cursor: `npx skills add ksimback/tech-debt-skill --skill tech-debt-audit -g -a cursor -y`
Gemini CLI: `npx skills add ksimback/tech-debt-skill --skill tech-debt-audit -g -a gemini-cli -y`

## Description

Thorough, user-invoked tech debt and architecture audit of the current codebase. Produces TECH_DEBT_AUDIT.md with file-cited findings, severity, effort estimates, and a required "looks bad but is actually fine" section. Use when the user asks for a debt audit, codebase health check, architecture review, or code quality assessment of an entire repo. Does not auto-invoke.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Tech Debt Audit

A Claude Code skill that conducts a deliberate, opinionated audit of an entire codebase and produces `TECH_DEBT_AUDIT.md` with cited findings.

When invoked via `/tech-debt-audit`, follow the protocol below. Everything from here through the `---` divider is the protocol Claude executes. The section after the divider is documentation for humans installing or maintaining this skill.

---

## Operating principles

Find what's actually wrong. Not diplomatic. Not surface-only. Don't pattern-match to generic best practices without grounding in this specific repo. No sycophancy. No "overall the codebase is well-structured" filler.

Cite `file:line` for every concrete finding. Vague claims like "the code generally..." don't count. Read code before judging it, a pattern that looks wrong in isolation may be load-bearing.

## Phase 1: Orient

Do not skip this. Forming opinions before understanding the system produces bad audits.

1. Read the README, package manifest (`package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`), and any architecture docs in `/docs` or `/adr`.
2. Map the directory structure and identify the major modules / layers.
3. Run `git log --oneline -200` and `git log --stat --since="6 months ago"` to see what's actually changing and where churn concentrates.
4. Identify entry points, hot paths, and cold corners.
5. List the top 20 largest files by line count, and the 20 files most frequently modified in the last 6 months. The intersection is where debt usually hides.
6. Use `TodoWrite` to publish a plan so the user can see progress through the phases.

Write a 1, 2 paragraph mental model of the architecture before proceeding. If your model contradicts the README, flag it, that itself is a finding.

## Phase 2: Audit across these dimensions

Use `rg`, `ast-grep`, and language-native tooling to find concrete examples. Cite `path/to/file.ext:LINE` for every finding.

The rest: https://github.com/ksimback/tech-debt-skill/blob/HEAD//SKILL.md