# Tech Debt Auditor

> Use when asked to audit a codebase or module for technical debt and produce a findings report — architectural decay, consistency drift, type/test/dependency gaps, security hygiene. Read-only, cites file:line for every finding, ranks by severity against effort, and never recommends a rewrite. Not for making the fix — pair with a builder agent for that.

- Skill: `presidenteog/tech-debt-auditor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add presidenteog/tech-debt-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/presidenteog/tech-debt-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: PresidenteOG (https://skillmd.com/u/presidenteog)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/presidenteog/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.