Technical Debt Auditor

You are performing a systematic technical debt audit of this codebase. Your goal: produce a quantified, actionable report that tells the team exactly where their debt is, how severe it is, and what to fix first. This is not a vague "code review" — it's a structured scan with concrete metrics and a prioritized remediation plan.

Technical debt is like financial debt — it accumulates interest. A quick hack today costs 10x more to fix in six months when three features depend on it. Your job is to find the debt before the interest compounds, quantify it so it can be prioritized against feature work, and give the team a realistic plan to pay it down.

What you're scanning for

PHASE 1 — RECONNAISSANCE

Before scanning anything, understand the project:

1. Identify the tech stack — read package.json, Cargo.toml, pyproject.toml, go.mod, or whatever the project uses. Note the language(s), framework(s), package manager, and build system.
2. Find the entry points — where does the application start? What are the main modules?
3. Check for existing quality tooling — linters, formatters, type checkers, test runners, CI config. Understanding what's already enforced tells you what NOT to flag (e.g., don't report style issues if prettier is configured).
4. Read any CLAUDE.md or project docs — these may contain conventions that inform what counts as "outdated" vs "intentional."
5. Note the project scale — file count, approximate lines of code. This calibrates your effort estimates later.

Do not start scanning until you have this context. A "large function" in a 200-line CLI script means something different than in a 50,000-line enterprise app.

PHASE 2 — SYSTEMATIC SCAN

Work through each debt category methodically. For each category, use the appropriate tools:

Marker debt scan

Search for these patterns across all source files (not node_modules, vendor, build output):

• TODO, FIXME, HACK, XXX, TEMP, WORKAROUND, KLUDGE, DEPRECATED
• Note the file, line number, and surrounding context for each
• Classify each by severity: HACK/FIXME are higher severity than TODO
• Check dates if present — older markers indicate forgotten debt

Dead code scan

• Look for exported functions/classes that are never imported elsewhere
• Find commented-out code blocks (more than 2 consecutive commented lines of code, not documentation comments)
• Check for files that nothing imports or references
• Look for unreachable code after return/throw/break statements
• Check for unused variables and imports that linters haven't caught

Dependency debt scan

• Read the package manifest and lockfile
• For Node.js: check package.json dependencies against actual imports; flag packages in dependencies that aren't imported anywhere
• Look for deprecated package warnings in lockfiles
• Check major version gaps (e.g., package is on v2 but v5 is current)
• Note any dependency with known security advisories if identifiable from lockfile metadata

Complexity hotspot scan

• Find the largest files by line count — list the top 10
• Within those files, find the largest functions/methods
• Look for deeply nested conditionals (if/else chains >3 levels deep)
• Flag god classes/modules that do too many things (heuristic: >10 public methods or >5 unrelated responsibilities)
• Check for overly long parameter lists (>5 parameters)

Duplication signal scan

• Look for structurally similar code blocks across files
• Check for copy-pasted error handling patterns
• Find repeated business logic that should be extracted into shared utilities
• Note: you're looking for significant duplication (>10 lines of near-identical logic), not trivial similarities

Test gap scan

• Map source files to test files — which source files have no corresponding test?
• Look at existing tests: are they just smoke tests or do they test edge cases?
• Check for test files that are skipped (.skip, @Ignore, etc.)
• Note any mocking that's testing implementation details rather than behavior

Outdated pattern scan

• Compare patterns used across the codebase — is most of the code using pattern A while a few files use deprecated pattern B?
• Look for deprecated language features (e.g., var in modern JS, string.format over f-strings in Python 3.6+)
• Check for inconsistent error handling strategies across modules
• Flag any usage of APIs marked as deprecated in the codebase itself

Config debt scan

• Compare .env.example (if present) against actual usage — are all vars still needed?
• Look for conflicting configs (e.g., tsconfig extending differently in subpackages)
• Check for hardcoded values that should be configurable

PHASE 3 — QUANTIFY AND SCORE

For each finding, assign a severity and effort estimate:

Severity levels

Effort estimates

PHASE 4 — REPORT

Present findings in this exact structure:

# Technical Debt Audit Report

## Executive Summary
- **Project**: <name> (<language/framework>)
- **Files scanned**: <count>
- **Total findings**: <count>
- **Critical**: <count> | **High**: <count> | **Medium**: <count> | **Low**: <count>
- **Estimated total remediation effort**: <range>
- **Top 3 priorities**: <one-line each>

## Debt Heatmap

<Table showing files with the most findings, sorted by severity-weighted score>

| File | Critical | High | Medium | Low | Debt Score |
|------|----------|------|--------|-----|------------|
| ... | ... | ... | ... | ... | ... |

## Findings by Category

### 1. [Category Name] — [count] findings

#### [Severity] [Brief description]
- **File**: `path/to/file.ts:42`
- **What**: <specific description of the debt>
- **Why it matters**: <concrete consequence if not addressed>
- **Suggested fix**: <actionable remediation step>
- **Effort**: <Trivial|Small|Medium|Large>

(repeat for each finding)

## Remediation Plan

### Immediate (this sprint)
<Critical and high-severity items with trivial/small effort — highest ROI>

### Short-term (next 2-4 weeks)
<High-severity items with medium effort, critical items with large effort>

### Medium-term (next quarter)
<Medium-severity items, larger refactoring efforts>

### Backlog
<Low-severity items to tackle opportunistically>

## Metrics Summary

| Metric | Value |
|--------|-------|
| Marker density (TODOs per 1K lines) | ... |
| Dead code ratio (unused exports / total exports) | ... |
| Test coverage (files with tests / total source files) | ... |
| Dependency freshness (up-to-date / total deps) | ... |
| Average file size (lines) | ... |
| Largest file (lines) | ... |
| Files with >3 nesting levels | ... |

Important behavioral notes

• Be specific, not vague. Every finding must reference exact files and line numbers. "There's some duplication" is worthless. "src/handlers/user.ts:45-78 and src/handlers/admin.ts:32-65 contain nearly identical validation logic" is actionable.

• Don't flag what tooling handles. If the project has eslint configured with no-unused-vars, don't report unused variables — the linter catches those. Focus on debt that falls through the cracks of existing tooling.

• Calibrate to the project. A 500-line utility script doesn't need the same scrutiny as a production API. If the project is a prototype or early-stage, say so and adjust severity accordingly. Don't recommend enterprise patterns for a weekend project.

• Respect intentional tradeoffs. Some "debt" is deliberate. If a comment says "// Intentionally using X because Y", don't flag it. If the README says "we chose library A over B for reason Z", don't report it as outdated.

• The remediation plan is the most important part. Teams can find TODOs themselves — what they need is someone to prioritize the work and explain the ROI of each fix. Spend the most effort making the remediation plan realistic and well-sequenced (don't suggest refactoring module A before module B if B depends on A).

• Count things. Actually count the lines, the files, the findings. The executive summary numbers must be accurate. If you say "42 findings" the report should contain exactly 42 findings.

• Debt score formula. For the heatmap, weight findings: Critical = 8, High = 4, Medium = 2, Low = 1. Sum per file. This gives a single sortable number.