yknothing Tech Debt Management
Technical debt is a loan against your future velocity. Track it, price it, and pay it down strategically.
Context
Every codebase accumulates technical debt -- shortcuts taken, technologies that aged, architectures that evolved beyond their original design.
See context notes.
Inputs
I/O contract notes define required inputs and authority.
Process
Step 1: Identify Debt from Repeated Evidence
Catalog debt from multiple sources:
- Code review findings tagged as "tech debt"
- Retrospective actions that imply recurring structural fixes
- Postmortems showing the same release, rollback, or observability weakness
- Architecture drift (system no longer matches the architecture doc)
- Missing tests or guards in critical paths
- Operational toil that repeats because the system boundary is weak
Separate:
- one-off defects to fix directly
- feature work that belongs in normal roadmap planning
- real debt that is accruing interest every cycle
Step 2: Classify Debt Type
Use the Technical Debt Quadrant (Martin Fowler):
| Deliberate | Inadvertent | |
|---|---|---|
| Prudent | "We know this is a shortcut, we'll fix it in v2" | "Now we know how we should have done it" |
| Reckless | "We don't have time for design" | "What's a design pattern?" |
Prudent deliberate debt is a valid business choice. Reckless debt needs prevention, not just remediation.
Step 3: Quantify Impact and Interest
For each debt item, estimate its "interest rate" -- the ongoing cost:
- How much developer time does it waste per sprint?
- What risk does it expose (security, reliability)?
- Does it block other improvements?
- What's the remediation cost?
- Does it widen brownfield coexistence or release-boundary risk?
Step 4: Prioritize
Rank by: (impact per sprint) / (remediation cost). High-interest, low-cost debt is fixed first.
Favor debt items that:
- reduce recurrence of known incidents
- remove unsafe manual workarounds
- strengthen handoffs between lifecycle phases
Step 5: Allocate Capacity
Dedicate a consistent percentage of sprint capacity to debt reduction:
- 20% is a common target for healthy codebases
- 30-40% for codebases with significant accumulated debt
- Track debt reduction as a team metric
For each top debt item, define:
- owner
- target window
- success signal
- next lifecycle destination (
pc-intake,planning,implementation, ordelivery)
Outputs
Produce only declared outputs at their documented quality boundary.
Quality Gate
- Debt registry is current and accessible to the team
- Top debt items have remediation plans with effort estimates
- Each prioritized item has owner, timeline, and next lifecycle destination
- Sprint capacity is allocated for debt reduction
- Debt trends tracked over time (is it growing or shrinking?)
Anti-Patterns
- Ignoring debt until crisis -- By then, remediation cost has multiplied.
- "Debt sprint" -- A one-time debt cleanup sprint doesn't work. Debt accumulates continuously; reduction should be continuous too.
- Tracking without acting -- A beautiful Jira board of debt items that never gets worked on.
- Gold-plating as debt reduction -- Rewriting working code for aesthetic reasons is not debt reduction. Focus on items with measurable impact.
- Debt bucket for every annoyance -- If everything is debt, nothing is prioritized. Use evidence and recurrence, not frustration alone.