---
name: tech-debt-triage
title: Technical Debt Triage
description: "Systematic framework for assessing, categorizing, and prioritizing technical debt. Produces a debt inventory with impact scores, remediation cost estimates, and a prioritized action plan. Turns vague \"we should refactor this\" into concrete decisions: what to fix, what to live with, what to schedule, and what to delete."
category: coding
tags:
  - dług-techniczny
  - priorytetyzacja
  - refaktoryzacja
  - architektura
  - planowanie
  - zarządzanie
requires:
  - Claude
source: https://madejski.ai/skilloteka/tech-debt-triage
locale: en
license: MIT
---

# Technical Debt Triage

## What This Skill Does

Turns vague "we should refactor this" feelings into concrete, prioritized decisions. Produces a technical debt inventory with impact analysis and a clear action plan.

The skill answers three questions:
1. **What debt do we actually have?** (inventory)
2. **Which debt is hurting us most?** (prioritization)
3. **What should we do about it?** (action plan)

## Debt Categories

| Category | Description | Example |
|----------|-------------|---------|
| **Architecture** | Structural decisions that limit the system | Monolith that should be services |
| **Design** | Code organization and pattern violations | God class, circular dependencies |
| **Code Quality** | Readability, duplication, complexity | 2000-line file, copy-paste logic |
| **Testing** | Missing or inadequate test coverage | No integration tests, flaky tests |
| **Infrastructure** | Outdated deps, missing automation | 3-year-old framework version |
| **Documentation** | Missing or stale docs | README from initial commit |
| **Security** | Known vulnerabilities not yet addressed | Deprecated auth library |

## Impact Scoring Matrix

Each debt item gets two scores (1-5):

**Pain Score** — How much is this hurting us today?
- 5: Blocking feature work, causing incidents
- 4: Slowing every sprint significantly
- 3: Causes regular friction
- 2: Annoying but workaround exists
- 1: Theoretical concern, no current pain

**Risk Score** — How dangerous is leaving this?
- 5: Security vulnerability or data loss risk
- 4: System stability at risk under load
- 3: Will become critical within 3 months
- 2: Will become painful within 6 months
- 1: Low risk, long time horizon

**Priority = Pain x Risk** (1-25 scale)

## Remediation Cost Estimation

For each item, estimate:
- **T-shirt size**: XS (hours) | S (1-2 days) | M (3-5 days) | L (1-2 weeks) | XL (sprint+)
- **Risk of remediation**: How likely is this fix to introduce new problems?
- **Dependencies**: What else needs to change?

## Action Categories

Based on priority vs. cost:

| | Low Cost | High Cost |
|---|---|---|
| **High Priority** | **Fix Now** — quick wins that reduce pain | **Schedule** — plan a dedicated sprint |
| **Low Priority** | **Opportunistic** — fix when touching that code | **Accept** — document and move on |

Plus one special category:
- **Delete** — code/features nobody uses. Best refactoring is deletion.

## Process

1. **Inventory** — scan the codebase, collect known debt items from the team
2. **Categorize** — assign each item to a debt category
3. **Score** — rate pain and risk for each item
4. **Estimate** — t-shirt size the remediation effort
5. **Prioritize** — sort by priority score, group into action categories
6. **Plan** — produce a concrete timeline: what this sprint, next sprint, this quarter

## Output Format

```markdown
## Technical Debt Triage: {project name}

### Debt Inventory

| # | Item | Category | Pain | Risk | Priority | Cost | Action |
|---|------|----------|------|------|----------|------|--------|
| 1 | ... | Architecture | 5 | 4 | 20 | L | Schedule |
| 2 | ... | Security | 3 | 5 | 15 | S | Fix Now |

### Fix Now (this sprint)
- Item 2: {description + specific fix approach}

### Schedule (dedicated effort)
- Item 1: {description + scope + suggested timeline}

### Opportunistic (when touching that code)
- ...

### Accept (document and move on)
- ...

### Delete candidates
- ...
```

## Anti-Patterns

- Listing debt without scoring it (everything feels equally important)
- Treating all debt as equal priority
- Refactoring without measuring impact
- Perfectionism — some debt is fine to live with
- Ignoring the "delete" option — unused code is the worst debt