Skip to content
Back to search

tech-debt-audit

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ksimback-tech-debt-skill/badge.svg)](/listings/ksimback-tech-debt-skill)

HTML

<a href="/listings/ksimback-tech-debt-skill"><img src="/api/listings/ksimback-tech-debt-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Personal install (available across all your projects):

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):

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 it's available:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 225 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: tech-debt-audit
  3. 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.
  4. disable-model-invocation: true
  5. ---
  6. # Tech Debt Audit
  7. A Claude Code skill that conducts a deliberate, opinionated audit of an entire codebase and produces `TECH_DEBT_AUDIT.md` with cited findings.
  8. 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.
  9. ---
  10. ## Operating principles
  11. 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.
  12. 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.
  13. ## Phase 1: Orient
  14. Do not skip this. Forming opinions before understanding the system produces bad audits.
  15. 1. Read the README, package manifest (`package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`), and any architecture docs in `/docs` or `/adr`.
  16. 2. Map the directory structure and identify the major modules / layers.
  17. 3. Run `git log --oneline -200` and `git log --stat --since="6 months ago"` to see what's actually changing and where churn concentrates.
  18. 4. Identify entry points, hot paths, and cold corners.
  19. 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.
  20. 6. Use `TodoWrite` to publish a plan so the user can see progress through the phases.
  21. 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.
  22. ## Phase 2: Audit across these dimensions
  23. Use `rg`, `ast-grep`, and language-native tooling to find concrete examples. Cite `path/to/file.ext:LINE` for every finding.
  24. 1. **Architectural decay** — circular deps, layering violations, god files (>500 LOC) and god functions, duplicated logic across 3+ sites where an abstraction should exist, abstractions that exist but nobody uses, dead code (unused exports, unreachable branches, stale commented-out blocks).
  25. 2. **Consistency rot** — multiple ways of doing the same thing (HTTP clients, error handling, logging, config loading, validation, date handling). Naming drift. Folder structure that no longer reflects what the code actually does.
  26. 3. **Type & contract debt** — `any` / `unknown` / `as any` / `# type: ignore` / loose dicts. Untyped API boundaries. Missing schema validation at trust boundaries.
  27. 4. **Test debt** — run coverage if available; identify gaps on critical paths. Tests that assert implementation rather than behavior. Skipped or flaky tests. High-churn files with no tests.
  28. 5. **Dependency & config debt** — `npm audit` / `pip-audit` / `cargo audit` for CVEs. Unused deps. Duplicate deps doing the same job. Env var sprawl (referenced but not documented; defaults inconsistent across envs).
  29. 6. **Performance & resource hygiene** — N+1 queries, sync work in async paths, blocking I/O on hot paths, uncleaned listeners or handles, unnecessary serialization.
  30. 7. **Error handling & observability** — swallowed exceptions, blanket catches, errors logged but not handled, inconsistent error shapes across modules, missing structured logs on critical paths.
  31. 8. **Security hygiene** — hardcoded secrets, string-concat SQL, missing input validation at trust boundaries, permissive auth or CORS, weak crypto.
  32. 9. **Documentation drift** — README claims that don't match reality, comments that contradict adjacent code, public APIs without docstrings.
  33. ## Phase 3: Deliverable
  34. Write to `TECH_DEBT_AUDIT.md` in the repo root with this structure:
  35. - **Executive summary** — max 10 bullets, ranked by impact.
  36. - **Architectural mental model** — your understanding of the system as it actually is.
  37. - **Findings table** — columns: `ID | Category | File:Line | Severity (Critical/High/Medium/Low) | Effort (S/M/L) | Description | Recommendation`. Aim for 30–80 findings; padding past that is noise.
  38. - **Top 5 "if you fix nothing else, fix these"** — with concrete diff sketches or refactor outlines, not vague advice.
  39. - **Quick wins** — Low effort × Medium+ severity, as a checklist.
  40. - **Things that look bad but are actually fine** — calls you considered flagging and chose not to, with reasoning. **This section is required.** If it's empty, you didn't look hard enough.
  41. - **Open questions for the maintainer** — things you couldn't tell were debt vs. intentional.
  42. ## Rules
  43. - Cite `file:line` for every concrete finding.
  44. - If unsure whether something is debt or intentional, ask in the open questions section — don't assert.
  45. - Don't recommend rewrites. Recommend specific, scoped changes.
  46. - Don't pad. If a category has nothing material, write "Nothing material" and move on.
  47. - No sycophancy. Tell the user what's broken.
  48. ## Stack-specific tooling
  49. Detect the stack from the manifest and run the relevant tools. Run them in parallel when possible.
  50. - **TypeScript / JavaScript** — `npm audit`, `npx knip` (dead exports), `npx madge --circular` (circular deps), `npx depcheck` (unused deps), `tsc --noEmit` for type drift.
  51. - **Python** — `pip-audit`, `ruff check`, `vulture` (dead code), `pydeps --show-cycles`, `mypy --strict` for type drift.
  52. - **Rust** — `cargo audit`, `cargo udeps`, `cargo machete`, `cargo clippy -- -W clippy::pedantic`.
  53. - **Go** — `govulncheck`, `go vet`, `staticcheck`, `golangci-lint run`.
  54. If a tool isn't installed, note it in the audit and move on rather than blocking. Do not install dev tools globally without permission.
  55. ## Large repos: spawn subagents
  56. If the repo is >50k LOC or has >5 top-level modules, dispatch subagents (Task tool) in parallel — one per module — and synthesize their reports. Serial reading on a large repo eats the context window before findings can be written.
  57. Each subagent gets: scope (one module), the dimensions list above, the citation requirement, and a 200-finding cap. The main agent merges, dedupes, and ranks.
  58. ## Repeat-run mode
  59. If `TECH_DEBT_AUDIT.md` already exists in the repo, read it first. Mark resolved findings as `RESOLVED`, update stale ones, and tag new findings with `NEW`. This turns the audit into a living document tracked over time.
  60. ---
  61. # Project documentation
  62. Everything below is for humans installing, using, or contributing to this skill. It is not part of the audit protocol.
  63. ## Installation
  64. Personal install (available across all your projects):
  65. ```bash
  66. mkdir -p ~/.claude/skills/tech-debt-audit
  67. ```
  68. ```bash
  69. curl -o ~/.claude/skills/tech-debt-audit/SKILL.md https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md
  70. ```
  71. Or for a project-only install (just this repo):
  72. ```bash
  73. mkdir -p .claude/skills/tech-debt-audit && cp /path/to/SKILL.md .claude/skills/tech-debt-audit/SKILL.md
  74. ```
  75. Verify it loaded:
  76. ```bash
  77. echo "/skills" | claude
  78. ```
  79. ## Usage
  80. In Claude Code, in the repo you want audited:
  81. ```
  82. /tech-debt-audit
  83. ```
  84. That's it. Output goes to `TECH_DEBT_AUDIT.md` in the repo root. First run takes 5–20 minutes depending on repo size; subsequent runs in repeat-run mode are faster.
  85. ## Philosophy
  86. Most "code review" prompts produce a bulleted list of generic best-practice violations dressed up as findings. This skill is built to avoid that failure mode. Three design choices do most of the work:
  87. **Forced orientation before judgment.** Phase 1 isn't optional decoration. Without a real mental model of the architecture, every Phase 2 finding is just pattern-matching against generic heuristics. Reading `git log` for churn data is what surfaces the files that *actually* have debt versus the files that just look messy.
  88. **File:line citations on every finding.** This is the single biggest quality lever. A finding without a citation is a vibe. Vibes don't get fixed.
  89. **The "looks bad but is actually fine" section is required.** This is the one most people remove when adapting the prompt. Don't. Forcing the model to surface the calls it considered making and chose not to is what separates a real audit from a checklist regurgitation. If that section is empty, the audit is shallow.
  90. The skill also explicitly forbids recommending rewrites and forbids padding categories. Both are common LLM failure modes — rewriting is easier than diagnosing, and padding makes outputs feel thorough when they aren't.
  91. ## What you get
  92. `TECH_DEBT_AUDIT.md` looks like this in shape:
  93. ```
  94. # Tech Debt Audit — <repo name>
  95. Generated: 2026-04-25
  96. ## Executive summary
  97. - 3 Critical findings, 12 High, 31 Medium, 18 Low
  98. - Largest debt concentration: src/payments/* (god module, 4 of 3 Critical findings)
  99. - ...
  100. ## Architectural mental model
  101. The system is a [...]
  102. ## Findings
  103. | ID | Category | File:Line | Severity | Effort | Description | Recommendation |
  104. |----|----------|-----------|----------|--------|-------------|----------------|
  105. | F001 | Architectural decay | src/payments/processor.ts:1240 | Critical | L | 1,400-line god class handling routing, validation, retry, and reconciliation | Extract retry and reconciliation into separate services |
  106. | ... |
  107. ## Top 5
  108. 1. **F001 — Decompose payments/processor.ts** ...
  109. ## Quick wins
  110. - [ ] F042: Remove unused dep `lodash.merge` (replaced by native ...)
  111. - [ ] ...
  112. ## Things that look bad but are actually fine
  113. - The deeply nested callback pattern in `src/legacy/webhooks.ts` looks like a refactor target, but it preserves ordering guarantees that the queue-based replacement would break. Leave it.
  114. - ...
  115. ## Open questions
  116. - Is `src/experiments/` intentionally untested, or did it fall through?
  117. - ...
  118. ```
  119. ## Adaptation notes
  120. **Project-level overrides.** A `.claude/skills/tech-debt-audit/SKILL.md` in a specific repo overrides the global one. Useful when a project needs custom dimensions — e.g., an agent codebase might add "prompt injection surface area" or "tool-call cost per turn" as audit categories.
  121. **Mid-audit course correction.** After Phase 1 completes, you can interrupt 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. Worth doing on first run for any new codebase.
  122. **Tuning severity calibration.** If the model is over- or under-flagging, edit the Phase 2 dimensions list to add explicit thresholds. Example: change "god files (>500 LOC)" to ">800 LOC" if your codebase has a higher baseline.
  123. **Adding categories.** The 9 dimensions in Phase 2 are a starting point. Add domain-specific ones for your stack — accessibility for frontend, IaC drift for infra, model evals for ML, prompt versioning for LLM apps.
  124. **Splitting into supporting files.** As this SKILL.md grows, you can extract sections into sibling files (`severity-rubric.md`, `stack-tooling.md`) and reference them from the protocol. Claude Code lazy-loads them only when needed.
  125. ## Limitations
  126. This is a static audit, not a security audit. It catches obvious security hygiene issues (hardcoded secrets, SQL injection patterns) but won't replace a real pen test or threat model.
  127. It won't catch business-logic bugs. Those require domain knowledge the model doesn't have.
  128. It can't tell intentional simplicity from accidental simplicity. The "open questions" section exists for exactly this reason — when in doubt, the skill asks rather than assuming.
  129. For very large repos (>200k LOC), even subagent dispatch can produce shallow results. Consider scoping to a module: `/tech-debt-audit src/payments`.
  130. ## Contributing
  131. PRs welcome. Before submitting:
  132. 1. Test against at least two real codebases of different stacks.
  133. 2. If you're adding a dimension, include a justification for why it isn't covered by the existing 9.
  134. 3. If you're tightening a rule, show a before/after audit excerpt demonstrating the improvement.
  135. The single design constraint: this skill must produce findings that engineers act on. Anything that pushes toward "feels comprehensive but nothing changes" is a regression.
  136. ## License
  137. MIT. Use it, fork it, ship it. Attribution appreciated but not required.
  138. ## Credits
  139. Built on the Claude Code Agent Skills standard. Inspired by the experience of working with Claude Code on codebases that got really messy over time.
README.md · README · 169 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # tech-debt-audit
  2. A Claude Code skill that produces a thorough, citable tech debt audit of your entire codebase — not a generic best-practices checklist.
  3. ```
  4. /tech-debt-audit
  5. ```
  6. 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.
  7. ## Why this exists
  8. 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.
  9. This skill is opinionated about avoiding that failure mode. Three design choices do most of the work:
  10. **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.
  11. **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.
  12. **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.
  13. 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.
  14. ## Why not the built-in Claude Code skills?
  15. Claude Code ships several skills that touch this space. None of them do what a debt audit needs to do.
  16. | Built-in | What it does | Why it's not a debt audit |
  17. |----------|--------------|----------------------------|
  18. | `/review` | PR-style code review of changes | Diff-scoped. Useful before merging a branch, not useful when you've inherited 80k LOC and want to know what's rotten. |
  19. | `/simplify` | Reduces over-engineered code in a specific area | Tactical, not architectural. Doesn't survey, doesn't cite, doesn't produce an artifact. |
  20. | `/debug` | Targets a specific failure or unexpected behavior | Reactive. You point it at a known problem; an audit's job is to *find* the problems. |
  21. | `/loop`, `/batch` | Workflow primitives for repeated or grouped tasks | Orchestration, not analysis. |
  22. What this skill adds:
  23. - **Whole-repo scope** across the nine dimensions that actually matter for debt: architectural decay, consistency rot, type & contract debt, test debt, dep & config debt, performance & resource hygiene, error handling & observability, security hygiene, and documentation drift.
  24. - **Multi-tool grounding.** Detects the stack and runs the right tools — `npm audit`, `knip`, `madge`, `depcheck` for TS/JS; `pip-audit`, `ruff`, `vulture`, `pydeps` for Python; `cargo audit`, `cargo udeps`, `cargo machete` for Rust; `govulncheck`, `staticcheck`, `golangci-lint` for Go — and folds the findings into the report.
  25. - **Subagent dispatch for large repos.** For codebases over ~50k LOC, the protocol parallelizes across modules so the main agent doesn't run out of context window before Phase 3.
  26. - **Persistent, citable artifact.** `TECH_DEBT_AUDIT.md` lives in your repo. You can commit it, review it in PRs, link to specific findings.
  27. - **Repeat-run mode.** On subsequent runs, resolved findings are marked `RESOLVED`, stale ones are updated, and new ones are tagged `NEW`. The audit becomes a living document.
  28. ## Installation
  29. Personal install (available across all your projects):
  30. ```bash
  31. mkdir -p ~/.claude/skills/tech-debt-audit
  32. ```
  33. ```bash
  34. curl -o ~/.claude/skills/tech-debt-audit/SKILL.md https://raw.githubusercontent.com/ksimback/tech-debt-skill/main/SKILL.md
  35. ```
  36. Project-only install (just this repo):
  37. ```bash
  38. 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
  39. ```
  40. Verify it's available:
  41. ```bash
  42. claude --print "/skills" | grep tech-debt-audit
  43. ```
  44. ## Usage
  45. In Claude Code, in the repo you want audited:
  46. ```
  47. /tech-debt-audit
  48. ```
  49. That's it. Output goes to `TECH_DEBT_AUDIT.md` in the repo root. First run takes 5–20 minutes depending on repo size. Subsequent runs in repeat-run mode are faster because the existing audit is used as a baseline.
  50. To audit only a specific subtree (useful for very large monorepos):
  51. ```
  52. /tech-debt-audit src/payments
  53. ```
  54. To get a mid-audit course correction (recommended on first run for any new codebase), interrupt after Phase 1 with:
  55. > Before Phase 2, tell me what surprised you in Phase 1 and what you want to investigate that isn't in the dimensions list.
  56. The best findings often come from things the prompt didn't anticipate.
  57. ## How it works
  58. Three phases:
  59. 1. **Orient** — read the manifest, map the structure, analyze `git log` for churn, identify the largest and most-modified files (their intersection is where debt usually hides), write a mental model.
  60. 2. **Audit** — sweep across nine dimensions using `rg`, `ast-grep`, and language-native tooling. Cite `file:line` on every finding.
  61. 3. **Deliverable** — write `TECH_DEBT_AUDIT.md` with executive summary, mental model, findings table, top-5 priorities, quick wins, the "looks bad but is fine" section, and open questions.
  62. The full protocol is in [`SKILL.md`](./SKILL.md).
  63. ## What the output looks like
  64. `TECH_DEBT_AUDIT.md` has this shape:
  65. ```
  66. ## Executive summary
  67. - 3 Critical findings, 12 High, 31 Medium, 18 Low
  68. - Largest debt concentration: src/payments/* (3 of 3 Critical findings)
  69. - ...
  70. ## Findings
  71. | ID | Category | File:Line | Severity | Effort | Description | Recommendation |
  72. | F001 | Architectural decay | src/payments/processor.ts:1240 | Critical | L | 1,400-line god class handling routing, validation, retry, and reconciliation | Extract retry and reconciliation into separate services |
  73. | ...
  74. ## Top 5
  75. 1. F001 — Decompose payments/processor.ts: ...
  76. ## Quick wins
  77. - [ ] F042: Remove unused dep `lodash.merge` (replaced by native ...)
  78. - [ ] ...
  79. ## Things that look bad but are actually fine
  80. - The deeply nested callback pattern in src/legacy/webhooks.ts looks like a refactor target, but it preserves ordering guarantees the queue-based replacement would break. Leave it.
  81. - ...
  82. ## Open questions for the maintainer
  83. - Is src/experiments/ intentionally untested, or did it fall through?
  84. - ...
  85. ```
  86. ## Customization
  87. The skill is designed to be forked and adapted. Common modifications:
  88. - **Add domain-specific dimensions.** The nine in Phase 2 are a starting point. Frontend repos can add accessibility; ML repos can add eval drift; LLM apps can add prompt versioning and tool-call cost; infra can add IaC drift.
  89. - **Tune severity thresholds.** If your codebase has a higher baseline (e.g., god files defined as >800 LOC instead of >500), edit the dimension definitions directly.
  90. - **Override per project.** A `.claude/skills/tech-debt-audit/SKILL.md` in a specific repo overrides the global one. Useful when one project needs custom dimensions the others don't.
  91. - **Split into supporting files.** As `SKILL.md` grows, extract sections into sibling files (`severity-rubric.md`, `stack-tooling.md`) and reference them. Claude Code lazy-loads supporting files, keeping the main protocol tight.
  92. ## Limitations
  93. This is a static audit, not a security audit. It catches obvious security hygiene issues (hardcoded secrets, SQL injection patterns, weak crypto) but won't replace a real pen test or threat model.
  94. It won't catch business-logic bugs. Those require domain knowledge the model doesn't have.
  95. It can't perfectly distinguish intentional simplicity from accidental simplicity. The "open questions" section exists for exactly this reason — when the skill is unsure, it asks rather than asserting.
  96. For very large repos (>200k LOC), even subagent dispatch can produce shallow results. Scope to a module or run section-by-section.
  97. ## Contributing
  98. PRs welcome. Before submitting:
  99. 1. Test against at least two real codebases of different stacks.
  100. 2. If you're adding a dimension, include a justification for why it isn't covered by the existing nine.
  101. 3. If you're tightening a rule, show a before/after audit excerpt demonstrating the improvement.
  102. The single design constraint: this skill must produce findings that engineers act on. Anything that pushes toward "feels comprehensive but nothing changes" is a regression and will be rejected.
  103. ## License
  104. MIT. Use it, fork it, ship it. Attribution appreciated but not required.
  105. ## Credits
  106. Built on the [Claude Code Agent Skills](https://code.claude.com/docs/en/skills) standard.
  107. Inspired by the experience of working with Claude Code on codebases that got really messy over time.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.