tech-debt

---

name: tech-debt description: > Document and prioritize technical debt. Use when the user says "tech debt", "legacy code", "this code is a mess", "refactoring plan", "we need to clean this up", "paying down debt", "this is hard to change", "how do we fix this codebase", or has code that's difficult to understand or modify

• even if they don't explicitly say "technical debt".

---

Overview

Based on "Working Effectively with Legacy Code" by Michael Feathers. Feathers' definition: legacy code is code without tests. His central technique: find the "seams" - places where you can insert test coverage without changing the code under test. Once a seam has test coverage, you can safely refactor. The discipline: never refactor without a safety net. Never add features to untested code without first covering it.

Workflow

Step 1: Define the debt

Before prioritizing, describe the debt specifically:

Debt item: [name]
Location: [file:line or module]
What it is: [one sentence description]
Why it's a problem: [what it makes harder]
Symptom: [what developers experience because of it]

Vague debt ("the codebase is messy") can't be prioritized. Specific debt can.

Step 2: Classify the debt type

Type	Description	Urgency
Reckless/Deliberate	Shortcuts taken knowingly ("we'll fix it later")	High
Reckless/Inadvertent	Mistakes made without knowing better	High
Prudent/Deliberate	Conscious tradeoff: ship now, fix later	Medium
Prudent/Inadvertent	Learned better approach after the fact	Low

Step 3: Find the seams (Feathers)

A seam is a place where you can change behavior without editing existing code - typically a function call boundary or an interface.

For each debt item:

• Where is the seam that would let you add tests without changing production code?
• What would you need to mock or stub to isolate this code?
• What's the minimum test coverage needed before safe refactoring?

Step 4: Estimate the cost of the debt

Dimension	Questions
Cost of carry	How much does this slow development each sprint?
Cost of fix	How many days to resolve?
Blast radius	How many systems/teams are affected?
Risk if ignored	What breaks if this is never fixed?

Step 5: Prioritize the backlog

Prioritize debt that:

• Has high cost of carry (slows the team every sprint)
• Sits in high-change areas (touched frequently)
• Blocks a planned feature

Deprioritize debt in stable areas that are rarely touched.

Step 6: Write the debt ticket

Title: [specific debt item]
Location: [file/module]
Type: [reckless/prudent x deliberate/inadvertent]
Impact: [what this costs the team per sprint]
Fix plan:
  1. Add seam tests: [specific tests to write first]
  2. Refactor: [what to change once tests exist]
  3. Verify: [how to confirm the refactor is safe]
Effort estimate: [days]
Priority: [P1/P2/P3]

Anti-Patterns

1. Refactoring without tests Bad: "Let me clean this up" without adding test coverage first. Good: Find the seam. Write tests. Then refactor. Tests prove you didn't break behavior.

2. Big bang rewrites Bad: "We'll rewrite the whole module from scratch." Good: Feathers: big rewrites fail. Incrementally improve with seam-by-seam coverage. Ship working code at every step.

3. Paying debt in high-risk sprints Bad: Refactoring core payment code the week before a major release. Good: Pay debt in low-risk windows. Prioritize timing as much as priority.

4. Debt without business context Bad: "This code is bad, we need to fix it." (to a PM or stakeholder) Good: "This debt costs us 2 days per sprint. Fixing it is a 5-day investment that pays back in 3 sprints."

Quality Checklist

• Debt is described specifically (file, module, or function - not "the codebase")
• Debt type classified
• Seam identified for each item (where to add tests safely)
• Cost of carry estimated in developer-days per sprint
• Cost to fix estimated
• Highest priority items are in high-change areas
• Debt ticket includes fix plan with seam tests as first step