# Analyze Tech Debt

> Analyze and prioritize technical debt with remediation plans. Use when user says "analyze the technical debt in this codebase", "what's the code quality like in this module", "identify what's slowing down our development", "assess the maintenance burden of this legacy code", "create a plan to pay down our tech debt", or "where should we focus our cleanup efforts".

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

```yaml
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?"
```