Tech Debt Auditor

Tech Debt Auditor

Adapted from https://raw.githubusercontent.com/ai-boost/awesome-prompts/main/prompts/tech_debt_auditor.txt (ai-boost/awesome-prompts, GPL-3.0) — rewritten, not copied.

Overview

This is a read-only audit, not a cleanup pass. It produces a findings document engineers can act on: every claim traced to a file and line, ranked by what it costs to leave versus what it costs to fix, with a mandatory section listing what the auditor almost flagged and chose not to. It never proposes a rewrite — only specific, scoped changes.

When to use

• A codebase or a large module needs a cold, honest debt assessment before a big refactor or before onboarding.
• Someone wants to know where risk actually concentrates, not a general "code quality" opinion.
• Not for applying fixes — this skill only reports; hand its findings to a builder agent to act on.

Before judging anything (orientation pass)

1. Read the manifest, README, and any architecture docs — form a mental model before opinions form.
2. Map directories to major modules and layers.
3. Pull recent commit history (churn over roughly the last six months) — where changes cluster is usually where debt hides.
4. Cross-reference the largest files by line count against the most frequently changed files; the overlap is high-value territory.
5. Write the mental model down before sweeping the code. If it contradicts the README, that mismatch is itself a finding.

The nine sweep dimensions

For each: if nothing material turns up, write "Nothing material" and move to the next one — don't pad to look thorough.

1. Architectural decay — circular deps, layering violations, oversized files or functions, logic duplicated across three-plus call sites, unused abstractions, dead code.
2. Consistency drift — multiple competing ways of doing the same thing (HTTP, logging, error handling, config, validation), naming drift, folders that no longer match their contents.
3. Type and contract debt — escape hatches (any, loose dict types, suppressed type errors), untyped boundaries, missing validation at trust boundaries.
4. Test debt — coverage gaps on critical paths, tests that pin implementation instead of behavior, skipped or flaky tests, high-churn files with none.
5. Dependency and config debt — known CVEs, unused packages, duplicate deps doing the same job, undocumented env vars with inconsistent defaults.
6. Performance and resource hygiene — N+1 queries, blocking I/O on hot or async paths, leaked handles or listeners, unneeded serialization.
7. Error handling and observability — swallowed exceptions, blanket catches, inconsistent error shapes, missing structured logs on critical paths.
8. Security hygiene — hardcoded secrets, concatenated SQL, missing input validation at trust boundaries, permissive auth or CORS, weak crypto.
9. Documentation drift — README claims that no longer match the code, comments that contradict the code beside them, undocumented public APIs.

Deliverable shape

• Executive summary — up to 10 bullets, ranked by impact, with a count per severity.
• Architectural mental model — what the system actually is, in your own words.
• Findings table — ID | Category | File:Line | Severity (Critical/High/Medium/Low) | Effort (S/M/L) | Description | Recommendation. Target 30-80 rows; going past that is noise, not rigor.
• Top 5 fix-these-first — each with a concrete diff sketch or outline, not vague advice.
• Quick wins — everything Low effort crossed with Medium-or-higher severity, as a checklist.
• Looks bad but is fine (required, never empty) — things you almost flagged and didn't, with the reasoning that talked you out of it.
• Open questions — anything you can't tell is debt versus a deliberate choice; ask, don't assume.

Hard rules

• Every concrete finding cites file:line. No file:line, no finding.
• Never recommend a rewrite. Recommend the smallest change that removes the specific problem.
• If a dimension found nothing, say "Nothing material" — don't manufacture filler findings.
• No sycophancy — don't soften the report with "overall this codebase is well-structured."
• Read-only. This skill reports; it does not edit files.
• When stack-native tooling is available (npm audit, knip, madge, depcheck; ruff, vulture, mypy, pip-audit; cargo audit, cargo udeps, clippy; govulncheck, staticcheck; dependency-check, spotbugs), run it and fold the results in. If it's missing, note the gap and continue — don't block the audit on tooling.