Tech Debt Assessment

Use this when the team knows tech debt exists but can't articulate what it is, how bad it is, or what to fix first. Also use when an engineering lead needs to make the case for debt reduction to product or business stakeholders. Produces a categorized debt inventory with impact scores, a prioritized remediation roadmap, and a stakeholder-ready summary.

Related skills: Use /delivery-diagnose if the symptom is declining velocity -- tech debt may be one of several root causes. Pair with /migration-plan when a debt item requires a major system migration. Use /code-review for per-PR debt identification. Feed remediation priorities into /technology-roadmap to incorporate debt work into the technology investment plan.

Process

Step 1: Gather inputs

Ask the user to provide:

1. System or codebase scope -- what's being assessed? A single service, a monolith, a platform, the whole stack?
2. Known pain points -- what slows the team down? What do engineers complain about? What's fragile?
3. Recent incidents -- any production issues caused or worsened by tech debt?
4. Team size and tenure -- how many engineers? How long have they been on this codebase?
5. Deployment and CI health -- build times, deployment frequency, flaky test rate, CI pass rate.
6. Business context -- upcoming features, growth plans, regulatory requirements that interact with the debt.

Step 2: Categorize the debt

Use the Fowler Tech Debt Quadrant to classify each debt item:

### Tech debt inventory -- {{system}}, {{date}}

#### Debt quadrant classification

|  | Deliberate | Inadvertent |
|--|-----------|-------------|
| **Reckless** | "We knew this was wrong but shipped anyway" | "We didn't know this was wrong until it broke" |
| **Prudent** | "We chose this trade-off knowingly and it served us" | "We've learned better approaches since we built this" |

For each identified debt item, capture:

| ID | Debt item | Quadrant | Category | Description | Age |
|----|-----------|----------|----------|-------------|-----|
| TD-1 | (name) | (Deliberate-Prudent / etc.) | (see categories below) | (one-line description) | (how long has it existed?) |

Debt categories:

• Architecture -- wrong abstractions, missing boundaries, scaling limitations, tight coupling
• Code quality -- duplication, naming, complexity, inconsistent patterns
• Testing -- missing tests, flaky tests, slow test suites, no integration tests
• Infrastructure -- outdated dependencies, unsupported platforms, manual deployment steps
• Documentation -- missing or outdated docs, tribal knowledge, no onboarding path
• Security -- known vulnerabilities, unpatched dependencies, missing access controls
• Data -- schema drift, migration debt, inconsistent data models across services

Step 3: Score impact

For each debt item, assess three impact dimensions:

### Impact scoring

| ID | Velocity drag | Incident risk | Feature cost multiplier | Combined score |
|----|--------------|---------------|------------------------|---------------|
| TD-1 | (1-5) | (1-5) | (1-5) | (sum) |

**Velocity drag (1-5):** How much does this slow down everyday development?
- 5: Blocks work daily. Engineers route around it constantly.
- 4: Slows most feature work. Adds hours to every PR.
- 3: Causes friction weekly. Some features take 2x longer.
- 2: Occasional annoyance. Workarounds are known and cheap.
- 1: Negligible daily impact. Engineers barely notice it.

**Incident risk (1-5):** How likely is this to cause or worsen a production incident?
- 5: Actively causing incidents. Matter of time before a major one.
- 4: Known fragility. Minor incidents have already occurred.
- 3: Latent risk. Hasn't failed yet but failure mode is clear.
- 2: Low probability. Would require unusual conditions.
- 1: Minimal risk. Well-contained even if it fails.

**Feature cost multiplier (1-5):** How much does this increase the cost of planned work?
- 5: Makes planned features infeasible without addressing it first.
- 4: Doubles the cost of upcoming features.
- 3: Adds 50%+ to feature cost in this area.
- 2: Adds some cost but features are still viable.
- 1: No meaningful impact on upcoming feature costs.

Step 4: Prioritize remediation

Rank debt items using cost of delay vs. cost to fix:

### Prioritization matrix

| ID | Debt item | Combined score | Cost to fix (T-shirt) | Payback period | Strategic alignment | Priority |
|----|-----------|---------------|----------------------|---------------|-------------------|----------|
| TD-1 | (name) | (from Step 3) | S / M / L / XL | (when does the investment pay for itself?) | (which business objective does fixing this enable or de-risk?) | P1 / P2 / P3 / Defer |

**Cost to fix (T-shirt sizing):**
- **S:** < 1 week, 1 engineer, low risk
- **M:** 1-2 weeks, 1-2 engineers, moderate risk
- **L:** 2-4 weeks, requires planning, some coordination
- **XL:** > 4 weeks, cross-team coordination, migration involved

**Priority levels:**
- **P1 -- Fix now:** High impact, reasonable cost. Blocking or creating risk.
- **P2 -- Plan next:** High impact but larger cost, or moderate impact with low cost. Schedule in next 1-2 quarters.
- **P3 -- Track:** Low impact or high cost. Revisit quarterly.
- **Defer:** Prudent debt that's still serving its purpose. Don't fix what isn't broken.

Step 5: Build the remediation roadmap

### Remediation roadmap

**Phase 1: Quick wins (next 2 iterations)**
| Debt item | Action | Owner | Definition of done |
|-----------|--------|-------|-------------------|
| (P1 items with S/M cost) | (specific action) | (team or role) | (what "fixed" looks like) |

**Phase 2: Planned investment (next quarter)**
| Debt item | Action | Dependencies | Estimated effort | Milestone |
|-----------|--------|-------------|-----------------|-----------|
| (P1 items with L/XL cost + P2 items) | (specific action) | (blockers) | (weeks) | (checkpoint) |

**Phase 3: Ongoing maintenance**
- Debt budget: Allocate {{X}}% of capacity to debt reduction (recommend 15-20%)
- Review cadence: Reassess this inventory quarterly
- Prevention: (what practices reduce new debt -- code review standards, architecture reviews, design docs)

Step 5b: Investment framing

For the top 3 debt items by priority, generate executive-ready investment summaries that frame debt in business terms:

### Investment framing -- top 3 debt items

**1. {{debt item name}}**
If we don't address this, we risk {{specific business outcome}} by {{timeline}}. Fixing it costs {{effort estimate}} and unblocks {{business capability or planned feature}}. The interest payment we're currently paying is {{ongoing friction -- e.g., "2 engineer-days per iteration in workarounds"}}.

**2. {{debt item name}}**
(Same structure)

**3. {{debt item name}}**
(Same structure)

These summaries are designed for executive and product stakeholders who need to understand why engineering capacity should be allocated to debt work. Frame as business risk, not technical complaint. Feed these into /technology-roadmap to position debt remediation alongside new technology investments.

Step 6: Generate the stakeholder summary

Write a non-technical summary for product managers, directors, or executives:

### Stakeholder summary: Technical debt in {{system}}

**The situation:** (1-2 sentences -- what's the debt and why should non-engineers care?)

**The impact on delivery:** (how this affects the team's ability to ship features)
- Current velocity drag: (estimated % of capacity spent on debt-related friction)
- Projected trend: (getting better, stable, or getting worse?)

**The risk:** (what happens if we don't address it?)
- (Specific risk 1 -- e.g., "The payment service is running on an unsupported framework version with known security vulnerabilities")
- (Specific risk 2)

**The ask:** (what the engineering team needs)
- Short term: (X days/iterations for quick wins)
- Medium term: (Y% capacity allocation for planned work)
- Ongoing: (Z% capacity budget for debt maintenance)

**The payoff:** (what improves after remediation)
- (Specific benefit 1 -- e.g., "Feature delivery in the payment area returns to normal velocity")
- (Specific benefit 2)

Step 7: Discuss

Ask the user:

• Does the inventory capture the debt you're aware of? What's missing?
• Do the impact scores match your team's experience?
• Is the prioritization right, or are there business constraints that should reorder things?
• Who needs to see the stakeholder summary? Should I adjust the framing?
• Want me to break any P1 items into implementation stories?

Output location

Present the assessment as formatted text in the conversation or save to a file if requested.