Analyze Tech Debt

Technical Debt Analyzer

Identify and prioritize technical debt with evidence-ranked remediation plans.

When to Activate

• User mentions technical debt
• Code quality assessment needed
• Understanding what's slowing development
• Legacy code evaluation
• Maintenance burden analysis

Execution Process

1. Scope the target — Identify which packages, modules, or files to analyze. If no scope is given, use the entire repository.

2. Collect code signals — Use Glob and Grep to find: files over 500 lines, deeply nested code (≥4 levels of indentation), TODO/FIXME/HACK comments, and any types in TypeScript files.

3. Examine git history — Run git log --since="6 months ago" --format="%H %s" --stat to identify high-churn files. Run git log --oneline --grep="fix\|bug\|hotfix" -- <path> on suspect files to spot chronic bug areas.

4. Assess test presence — Use Glob("**/*.test.*") and Glob("**/*.spec.*") to find test files. Cross-reference with source files to identify untested modules. Compute the test-to-source file ratio (test file count / source file count) as a proxy for testing density — not a statement of line coverage.

5. Rank each item — Rate impact on a high / medium / low band and risk as critical/high/medium/low, then record the change's blast radius: how many files and call sites it touches, whether it changes a public interface, and whether the area has tests. Ground every band in the signals you actually collected (commit count, file size, nesting depth, missing tests), and cite that signal alongside the band.

   Do not estimate hours lost per month or hours to fix, and do not compute an ROI number from them. You have no data on this team's velocity; a formula over two invented inputs produces a figure that reads as measured and is not. Rank by band, cite the evidence, and let the reader supply their own effort numbers.

6. Write the report — Output a Debt Metrics Dashboard followed by a Prioritized Roadmap. Group items by the scope of the change each one requires, which you can observe from the code: Mechanical, Structural, or Architectural (defined under Prioritized Roadmap below). Order within each group by impact band. Do not label a group with an ROI or a duration.

Debt Categories

Code Debt

• Duplicated Code: Copy-paste, repeated logic
• Complex Code: High cyclomatic complexity, deep nesting
• Poor Structure: Circular dependencies, coupling issues

Architecture Debt

• Design Flaws: Missing abstractions, violations
• Technology Debt: Outdated frameworks, deprecated APIs

Testing Debt

• Coverage Gaps: Untested paths, missing edge cases
• Test Quality: Brittle, slow, or flaky tests

Documentation Debt

• Missing API docs, undocumented complex logic

Infrastructure Debt

• Manual deployments, missing monitoring

Impact Assessment

Rate each item against evidence you collected, not against invented cost figures:

• Velocity impact band (high/medium/low), justified by churn and complexity signals
• Quality signal: count of fix/bug/hotfix commits touching the file
• Risk assessment (critical/high/medium/low)
• Blast radius: files touched, call sites found, interface changed or not, tests present or not

Output Format

Debt Metrics Dashboard

high_churn_files:
  - path: src/auth/login.ts
    commits_6mo: 47
files_over_500_lines:
  count: 12
  worst: src/legacy/processor.ts (1842 lines)
todo_fixme_count:
  total: 83
  hotspots: [src/payments/, src/legacy/]
test_to_source_ratio:
  ratio: 45%
  note: proxy for testing density, not line coverage

Prioritized Roadmap

Group by observable blast radius, not by a guessed cost:

• Mechanical: contained to one file, no public interface changes, and the area already has tests — the change is a rewrite of existing behavior with a check already in place
• Structural: spans several files or changes an interface, so callers must be updated; state how many call sites you found and whether they are covered by tests
• Architectural: design-level change across modules, or a change to code with no test coverage at all — the shape has to be decided before it can be written

Order within each group by impact band.

Per-Item Format

Each item includes: location, description, impact band, its group from above, the specific signal that justifies both (e.g. "47 commits in 6 months, 12 of them fix commits; 9 call sites, none under test"), and the recommended fix. Cap the roadmap at the 20 highest-impact items and target under 200 lines; say how many items were left out so nothing looks hidden.

Examples

"Analyze the technical debt in the auth module"
"What's slowing down development in packages/legacy?"
"Create a cleanup roadmap for next quarter"
"Where should we focus refactoring efforts this sprint?"