Tech Debt Audit
Thorough, user-invoked tech debt and architecture audit of the current codebase.
Install
npx skills add ksimback/tech-debt-skill --skill tech-debt-audit -g -a claude-code -y- Repository
- ksimback/tech-debt-skill626
- Category
- Engineering
- Updated
- 6mo ago
- License
- See repository
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
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.
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.
- Read the README, package manifest (
package.json/pyproject.toml/Cargo.toml/go.mod), and any architecture docs in/docsor/adr. - Map the directory structure and identify the major modules / layers.
- Run
git log --oneline -200andgit log --stat --since="6 months ago"to see what's actually changing and where churn concentrates. - Identify entry points, hot paths, and cold corners.
- 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.
- Use
TodoWriteto 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.
