Skip to content

Tech Debt Triage

Convert a noisy debt backlog into a small, ranked, decision-ready list.

When to use

  • A repository has accumulated TODOs / FIXMEs / open issues that nobody groups or prioritizes.
  • Before starting a refactor, you need a defensible ordering.
  • The user wants "which thing should I fix first?" with reasoning.

What you produce

A single markdown report with two sections: 1. A ranked table of debt items with scoring. 2. An action plan for the top 3 items (smallest viable change, test plan, blast radius).

Procedure

  1. Collect candidates. Search the workspace for TODO/FIXME/HACK/XXX comments, open issues (if MCP/GitHub tools available), test skips, deprecated API uses, lint suppressions. Use the explore subagent for large codebases.
  2. Cluster. Group near-duplicates. A pattern repeated in 8 places is one item, not 8.
  3. Score each item on three 1-5 axes:
  4. Value (impact if fixed: bug surface, perf, security, DX).
  5. Effort (size of safe change including tests).
  6. Risk (chance of regression or breaking change).
  7. Compute priority = Value − (Effort × 0.5) − (Risk × 0.5). Round to nearest 0.5. Higher = do sooner.
  8. Sort and report. Top of table first.
  9. For top 3: propose smallest viable change, test plan, and a "stop / escalate" condition.

Report template

# Tech Debt Triage — <repo>

## Ranked items

| # | Item | Locations | Cluster size | Value | Effort | Risk | Priority |
| - | ---- | --------- | ------------ | ----- | ------ | ---- | -------- |
| 1 | ...  |           |              |       |        |      |          |

## Top 3 action plan

### 1. <item>
- Smallest viable change:
- Tests to add/update:
- Blast radius:
- Stop / escalate if:

### 2. <item>
...

### 3. <item>
...

Anti-patterns

  • Don't list every TODO; cluster first.
  • Don't recommend "rewrite everything"; that's not triage.
  • Don't drop items silently; everything goes in the table even if priority is low.
  • Don't propose changes that violate the bounded-edit rule.

Compatibility

Compatible with both project and user scopes. Read-only by default; the agent can choose to apply the top-1 fix if explicitly asked.