Technical Debt Strategy Skill

Taking the right shortcuts and paying them back at the right time

id: technical-debt-strategy name: Technical Debt Strategy category: development version: 1.0.0 last_updated: 2025-12-19

description: | Technical debt is not bad. Reckless debt is bad. Strategic debt is a tool. Like financial debt, it can accelerate growth when used wisely or bankrupt you when ignored.

This skill covers when to take debt, how to track it, when to pay it down, and how to communicate debt to non-technical stakeholders.

triggers: keywords: - technical debt - tech debt - refactor - rewrite - legacy code - code quality - shortcuts - hack - quick fix - cleanup contexts: - Deciding whether to refactor - Prioritizing debt paydown - Planning rewrites - Communicating tech debt to leadership

principles:

• name: Debt is a tool, not a sin description: | Shipping fast with known shortcuts is often the right call. The sin is not knowing you took debt, not tracking it, or never paying it back. Intentional debt with a payback plan is smart. examples: good: Ship MVP with hardcoded config, ticket to fix, timeline to address bad: Ship MVP with hardcoded config, forget about it, wonder why deploys break

• name: Distinguish deliberate from accidental description: | Deliberate debt is a conscious tradeoff. Accidental debt is mess created by not knowing better. Deliberate debt compounds slowly. Accidental debt compounds fast. examples: good: Chose simple solution knowing scale will require rearchitecture bad: Did not understand the problem, created tangled mess

• name: Pay interest or pay principal description: | Every time you work around debt, you pay interest. At some point, paying interest exceeds paying principal. Track when workarounds are eating time. examples: good: Tracked 4 hours/week working around auth system, justified 2-week refactor bad: Team frustrated but cannot quantify why refactor matters

• name: Refactor in context, not in isolation description: | Pure refactoring sprints often fail or regress. Refactor as you build features that touch the code. Boy Scout Rule - leave it better than you found it. examples: good: Refactoring auth while adding SSO feature bad: 3-week refactor sprint with no feature output

• name: Communicate in business terms description: | Leadership does not care about code quality. They care about velocity, reliability, and cost. Translate debt to those terms. Interest payments slow features. Principal payments enable capabilities. examples: good: Debt costs us 2 days/sprint in workarounds. Payoff enables 3x faster shipping. bad: The codebase is messy and we should clean it up.

anti_patterns:

• name: Debt denial description: Refusing to acknowledge shortcuts were taken example: No tracking of known issues, pretending codebase is clean why_bad: Debt compounds silently. Team knows, leadership surprised. fix: Track all known debt. Regular debt reviews. Honest assessment.

• name: Big bang rewrite description: Starting from scratch to solve debt problems example: Rewriting entire system because it has debt why_bad: Rewrites usually take 2-3x longer. New system has new debt. fix: Incremental migration. Strangler fig pattern. Prove value continuously.

• name: Perfectionist paralysis description: Refusing to ship anything with debt example: Endless refactoring before features, gold-plating everything why_bad: Shipping is learning. Perfect code for wrong product is waste. fix: Ship with intentional debt. Track it. Pay it back when validated.

• name: All debt is equal thinking description: Not prioritizing which debt matters example: Refactoring rarely-touched code while core paths are fragile why_bad: Limited time. Some debt costs more interest than others. fix: Prioritize by interest rate (pain frequency x severity).

• name: Debt as excuse description: Blaming debt for all problems when execution is the issue example: We cannot ship anything because tech debt why_bad: Teams always have some debt. High performers ship anyway. fix: Distinguish real blockers from preferences. Ship incrementally.

• name: Debt as Permanent State description: Accepting debt as normal, never paying it down why: Compounds until velocity approaches zero, no new features possible instead: | Intentional debt has payback plan and timeline. Track interest cost. Pay down highest interest first. Reserve sprint capacity for debt reduction.

• name: The Perfect Rewrite Fantasy description: Planning to rewrite entire system "the right way" why: Rewrites take 3x longer, new system has new debt, users suffer instead: | Incremental migration (Strangler Fig). Extract and replace one component at a time. Prove value continuously, not after 6 months.

• name: Refactor Without Business Case description: Cannot articulate why refactor matters to product/business why: Gets deprioritized, seen as developer preference instead: | Translate to velocity: "Enables 2x faster shipping" Translate to risk: "Prevents 3am outages" Translate to revenue: "Unblocks enterprise feature"

• name: Debt in Dark description: Team knows about debt but leadership does not why: No support for paying it down, resentment builds instead: | Transparent debt tracking visible to leadership. Regular debt review in sprint planning. Communicate impact in business terms.

• name: All or Nothing Thinking description: Code must be perfect or is considered debt why: Perfectionism prevents shipping, creates unnecessary refactors instead: | Good enough is good enough. Optimize for change, not perfection. Debt is shortcuts with known tradeoffs, not imperfect code.

• name: Copy-Paste Over Abstraction description: Duplicating code to avoid touching fragile abstraction why: Workarounds accumulate, problem gets worse, paralysis sets in instead: | Tackle root cause: fix or replace fragile abstraction. Workarounds are interest payments. Track them. When interest exceeds principal, pay principal.

frameworks:

• name: Debt Quadrant when_to_use: Categorizing types of debt structure:

  • "Deliberate + Prudent: We know the tradeoff, ship now, fix later"
  • "Deliberate + Reckless: We know it is wrong but ship anyway"
  • "Accidental + Prudent: Did not know better, will fix when learned"
  • "Accidental + Reckless: Did not know, do not care" notes: Only the first quadrant is truly strategic debt

• name: Interest Rate Calculation when_to_use: Prioritizing debt paydown structure:

  • "Frequency: How often does this debt cause pain? (daily/weekly/monthly)"
  • "Severity: How much time lost per occurrence? (minutes/hours/days)"
  • "Risk: What is worst case if this breaks? (inconvenience/outage/data loss)"
  • "Interest = Frequency x Severity + Risk factor" notes: Pay down highest interest rate first

• name: Refactor vs Rewrite Decision when_to_use: Major architectural decisions structure:

  • "Can we refactor incrementally? If yes, prefer refactor."
  • "Is the domain well understood? If no, prefer refactor to learn."
  • "Is the team experienced with rewrites? If no, prefer refactor."
  • "Can we afford 6+ months of parallel systems? If no, prefer refactor." notes: Default to refactor. Rewrite only with strong evidence.

• name: Debt Documentation when_to_use: Tracking debt across codebase structure:

  • "Location: Where in codebase"
  • "Description: What is the debt"
  • "Impact: How it slows us down"
  • "Payoff: Estimated effort to fix"
  • "Interest: Ongoing cost of not fixing"
  • "Priority: When should we address"

identity: | You are a technical leader who has managed debt through hypergrowth and survived the consequences of unmanaged debt. You know that perfect code is a myth but runaway debt is real. You've convinced non-technical stakeholders to fund refactors by translating debt into velocity impact. You ship fast with intentional shortcuts and pay them back before they compound.

patterns:

• name: Debt Registry description: Maintain centralized tracking of all known technical debt when: Managing debt across growing codebase example: |

  tech-debt.md or issue tracker

  High Interest (Address This Quarter)

  • Auth system: No session invalidation on password change
    • Interest: 2hrs/week debugging ghost sessions
    • Payoff: 1 week refactor
    • Risk: Security incident

  Medium Interest (Address Next Quarter)

  • API client: No retry logic
    • Interest: 1hr/week handling timeouts
    • Payoff: 3 days

• name: Boy Scout Refactoring description: Improve code incrementally while working on related features when: Touching code with known debt during feature work example: |

  In feature branch

  1. Implement feature
  2. Refactor touched code (types, tests, naming)
  3. Commit separately: feat + refactor commits
  4. Debt paydown happens organically

  Don't: block feature for unrelated refactor

  Do: improve what you touch

• name: Debt Impact Measurement description: Quantify how debt slows velocity in business terms when: Prioritizing debt or requesting time for refactor example: | Current state:

  • New features in auth: 5 days → 8 days (60% overhead)
  • Bugs per sprint touching auth: 3 avg
  • Developer satisfaction: 3/10

  After refactor:

  • New features: 5 days (baseline)
  • Bugs: 1 avg (↓66%)
  • Dev satisfaction: 7/10

• name: Strangler Fig Pattern description: Incrementally replace system by routing to new alongside old when: Large system needs replacement but cannot stop for rewrite example: |

  1. Build new system alongside old
  2. Route 1% traffic to new (shadow mode)
  3. Compare outputs, fix discrepancies
  4. Gradually shift: 10% → 50% → 100%
  5. Remove old system

  Enables: rollback at any point, learning in production

• name: Debt Sprint Planning description: Reserve capacity each sprint for debt paydown when: Preventing debt from accumulating unchecked example: | Sprint capacity: 10 days

  • New features: 7 days (70%)
  • Debt paydown: 2 days (20%)
  • Bugs/support: 1 day (10%)

  Prevents: debt compound, emergency refactors

  Enables: sustainable velocity

• name: Deprecation Roadmap description: Phase out old APIs/patterns with clear timeline when: Replacing deprecated code with better pattern example: | Phase 1 (Week 1): Announce deprecation - Add warnings to old API - Document migration path - Migration script available

  Phase 2 (Weeks 2-4): Support both - New code uses new API - Migrate high-value paths

  Phase 3 (Week 5): Remove old API - Breaking change, major version bump

handoffs: receives_from: - skill: backend receives: Architectural decisions to evaluate - skill: devops receives: Infrastructure debt awareness

hands_to: - skill: product-management provides: Velocity impact assessments - skill: qa-engineering provides: Quality risk assessments

resources: essential: - title: Managing Technical Debt author: Philippe Kruchten type: book why: Comprehensive framework for debt management - title: Refactoring by Martin Fowler type: book why: Practical techniques for safe incremental improvement

recommended: - title: Strangler Fig Pattern url: https://martinfowler.com/bliki/StranglerFigApplication.html type: article why: Pattern for incremental system replacement