Technical Debt Audit

Systematically identify, categorize, and prioritize technical debt. Produce an actionable refactoring roadmap with effort estimates and business impact.

Workflow

Step 1: Scan the Codebase

Analyze the project across multiple dimensions:

Dependency Health

# Check for outdated dependencies
npm outdated 2>/dev/null || pip list --outdated 2>/dev/null

# Check for known vulnerabilities
npm audit 2>/dev/null || pip-audit 2>/dev/null || safety check 2>/dev/null

# Check dependency count and tree depth
cat package.json | grep -c '"' 2>/dev/null
pip list --format=columns 2>/dev/null | wc -l

Code Complexity

# Find large files (often a smell)
find . -name "*.ts" -o -name "*.js" -o -name "*.py" | xargs wc -l 2>/dev/null | sort -rn | head -20

# Find TODO/FIXME/HACK comments
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" --include="*.ts" --include="*.js" --include="*.py" . | head -30

# Check for duplicate code patterns (rough heuristic)
grep -rn "function\|def \|class " --include="*.ts" --include="*.js" --include="*.py" . | wc -l

Test Coverage

# Check for test files
find . -name "*test*" -o -name "*spec*" | grep -v node_modules | head -20

# Ratio of test files to source files
echo "Source files:" && find src -name "*.ts" -o -name "*.js" | wc -l
echo "Test files:" && find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules | wc -l

Configuration and Build

# Check for lint config
ls .eslintrc* .prettierrc* .flake8 pyproject.toml tslint.json 2>/dev/null

# Check CI config
ls .github/workflows/* .gitlab-ci.yml Jenkinsfile .circleci/config.yml 2>/dev/null

# Check for Dockerfile optimization opportunities
cat Dockerfile 2>/dev/null

Step 2: Read and Analyze Key Files

Go beyond metrics. Read the actual code in high-traffic areas:

• Entry points (main files, route handlers, API controllers).
• Core business logic modules.
• Database access layer (ORM models, queries, migrations).
• Shared utilities and helper modules.
• Configuration and environment handling.

Look for:

• God classes/modules: Files doing too many things.
• Inconsistent patterns: Different approaches to the same problem in different places.
• Missing abstractions: Copy-pasted code that should be extracted.
• Leaky abstractions: Implementation details exposed across module boundaries.
• Dead code: Unused functions, unreachable branches, commented-out code.
• Hardcoded values: Magic numbers, hardcoded URLs, inline credentials.
• Missing error handling: Swallowed exceptions, unhandled promise rejections.
• Type safety gaps: any types, missing null checks, implicit conversions.

Step 3: Categorize the Debt

Organize findings into categories:

Step 4: Prioritize with Impact/Effort Matrix

Score each item on two axes:

• Impact (1-5): How much does fixing this improve reliability, velocity, or safety?
• Effort (1-5): How much time and risk is involved in fixing it?

               Low Effort    High Effort
High Impact  | QUICK WINS  | MAJOR PROJECTS |
Low Impact   | FILL-INS    | AVOID FOR NOW  |

Prioritize:

1. Quick wins (high impact, low effort) — do these first.
2. Major projects (high impact, high effort) — plan and schedule these.
3. Fill-ins (low impact, low effort) — do during slack time.
4. Avoid for now (low impact, high effort) — revisit later.

Step 5: Build the Roadmap

Create a phased plan that can be executed alongside feature work.

Output Format

# Technical Debt Audit: <Project Name>

**Date**: YYYY-MM-DD
**Scope**: <what was audited>
**Overall Health**: Good | Fair | Needs Attention | Critical

## Executive Summary

<2-3 sentences on the overall state and top priorities>

## Findings by Category

### Critical (fix immediately)

#### [TD-1] <Title>
**Category**: Security | Reliability
**Location**: <file(s) or area>
**Description**: <what the problem is>
**Impact**: <what could go wrong>
**Effort**: <estimated time>
**Recommendation**: <specific action>

### High Priority (plan for next quarter)

#### [TD-2] <Title>
...

### Medium Priority (schedule when possible)

#### [TD-3] <Title>
...

### Low Priority (opportunistic)

#### [TD-4] <Title>
...

## Metrics Summary

| Metric                  | Current | Target  | Notes                    |
|-------------------------|---------|---------|--------------------------|
| Known vulnerabilities   | 3       | 0       | 1 critical, 2 moderate   |
| Outdated dependencies   | 12      | < 5     | 3 major versions behind  |
| Files > 500 lines       | 8       | 0       | Largest: 1,200 lines     |
| TODO/FIXME count        | 47      | < 10    | 12 are > 6 months old    |
| Test coverage           | ~40%    | > 70%   | No integration tests     |

## Refactoring Roadmap

### Phase 1: Quick Wins (1-2 weeks)
- [ ] Fix critical security vulnerabilities (TD-1)
- [ ] Remove dead code and unused dependencies (TD-8)
- [ ] Add missing error handling in payment flow (TD-3)

### Phase 2: Foundation (1-2 sprints)
- [ ] Extract shared utilities from duplicated code (TD-5)
- [ ] Add integration tests for core flows (TD-6)
- [ ] Update major dependency versions (TD-4)

### Phase 3: Architecture (1 quarter)
- [ ] Refactor god module into focused services (TD-2)
- [ ] Implement proper logging and observability (TD-7)

## Maintenance Recommendations

- <ongoing practice to prevent debt accumulation>
- <tooling or process change>

Examples

User: "Audit the tech debt in this project" Action: Scan the codebase for dependency health, code complexity, test coverage, and patterns. Read key files. Produce a categorized, prioritized audit report with a phased roadmap.

User: "What should we refactor first?" Action: Identify the highest-impact, lowest-effort improvements. Focus on quick wins that unblock velocity or reduce risk.

User: "How's our code health?" Action: Produce a concise health assessment: dependency currency, test coverage, complexity hotspots, and a summary score.

Best Practices

• Tech debt is not inherently bad. It becomes a problem when it slows velocity or increases risk. Prioritize by impact, not by aesthetics.
• Always tie debt to business impact. "This module is messy" is not compelling. "This module causes 40% of our production incidents" is.
• Propose incremental improvements, not big-bang rewrites. Large rewrites fail more often than they succeed.
• Include debt reduction in regular sprint work (e.g., 20% of capacity). Debt-only sprints rarely get approved and signal a planning failure.
• Track debt over time. If the TODO count and vulnerability count grow every quarter, the process is not working.
• Distinguish between intentional debt (conscious trade-off for speed) and accidental debt (didn't know better). They require different responses.
• Quick wins build momentum and credibility. Start with those to demonstrate the value of debt reduction before proposing larger efforts.
• Automate detection where possible. Linting rules, dependency bots, and CI checks catch new debt before it accumulates.