Tech Debt

Technical Debt Management

Tech debt is borrowed time. Like financial debt, it's not inherently bad - but you need to track it, pay interest on it, and have a paydown plan.

What IS Tech Debt (And What Isn't)

Tech Debt

• Shortcuts taken deliberately to ship faster ("we'll fix this after launch")
• Code that worked when written but hasn't evolved with requirements
• Missing tests that make changes risky
• Outdated dependencies with known issues
• Architecture that doesn't fit current scale/requirements

NOT Tech Debt (Just Bad Code)

• Bugs (fix them now)
• Code that was never adequate (that's just poor engineering, not debt)
• "I'd write it differently" (style preferences aren't debt)
• Features that need redesign (that's product work, not debt)

Step 1: Inventory

Scan the codebase and catalog debt. Be specific.

Debt Record Template

ITEM: [specific description]
LOCATION: [files, modules, or systems affected]
TYPE: [code / architecture / dependency / testing / infrastructure]
IMPACT: [what it costs you TODAY - developer time, bugs, fragility, onboarding difficulty]
RISK: [what happens if you DON'T fix it - data loss, security, scaling failure]
EFFORT: [S / M / L / XL]
URGENCY: [blocking / degrading / annoying / dormant]

Where to Look

| Area | Signs of Debt | |------|--------------| | Hotspots | Files changed most frequently (git log). Frequent changes = fragile code. | | Bug clusters | Modules that generate the most bugs. | | Onboarding friction | "Nobody understands how this works" areas. | | Dependency audit | Unmaintained deps, major version gaps, known CVEs. | | Test coverage gaps | Core logic with no tests. | | Build/deploy pain | 30-min builds, manual deploy steps, flaky CI. | | Performance bottlenecks | Known slow paths everyone works around. | | Copy-paste code | Same logic in 5 places, each slightly different. |

Step 2: Categorize

| Category | Description | Examples | |----------|-------------|---------| | Deliberate-prudent | Known shortcut, planned payoff | "Ship with SQLite, migrate to Postgres next quarter" | | Deliberate-reckless | Known shortcut, no plan | "We'll figure it out later" (later never comes) | | Accidental-prudent | Learned better approach | "We didn't know about X pattern when we built this" | | Accidental-reckless | Didn't know, didn't care | Poor code quality, no reviews, no standards |

Focus on: deliberate-prudent (planned payoff) and accidental-prudent (now we know better). Reckless debt often means the code needs rewriting, not refactoring.

Step 3: Prioritize

Score each item on two axes:

Impact (How much does it cost you?)

• High: Slows every sprint, causes bugs, blocks features
• Medium: Periodic pain, occasional bugs, extra complexity
• Low: Annoyance, cosmetic, rarely encountered

Risk (What happens if you ignore it?)

• High: Security vulnerability, data loss, scaling cliff
• Medium: Growing maintenance cost, harder to hire/onboard
• Low: Suboptimal but stable

Priority Matrix

| | High Impact | Medium Impact | Low Impact | |--|-------------|---------------|------------| | High Risk | Fix NOW | Fix this quarter | Schedule | | Medium Risk | Fix this quarter | Schedule | Backlog | | Low Risk | Schedule | Backlog | Ignore |

Step 4: Making the Business Case

Engineers say: "We need to refactor." Business hears: "We want to stop shipping features."

Instead, frame debt in business terms:

| Tech Talk | Business Talk | |-----------|---------------| | "The auth module needs refactoring" | "Every security fix takes 3x longer because auth is tangled - next breach response will be slow" | | "We should upgrade the ORM" | "Our current version has 4 known CVEs. Upgrading unblocks 2 feature requests." | | "Tests are missing for payments" | "We can't safely change payment flow - last time an untested change caused $X in failed transactions" | | "The build is too slow" | "Engineers wait 25 min per build. That's X hours/week of lost productivity across the team." |

The Paydown Pitch

DEBT: [what]
COST OF CARRYING: [what it costs you per sprint/month in concrete terms]
COST TO FIX: [effort estimate]
PAYBACK PERIOD: [when the fix pays for itself]
RISK OF NOT FIXING: [worst case scenario and likelihood]

Step 5: Paydown Strategies

The 20% Rule

Reserve ~20% of sprint capacity for debt paydown. Every sprint. Non-negotiable. This is interest payment.

Boy Scout Rule

"Leave the code better than you found it." Small improvements alongside feature work. Rename a confusing function. Add a missing test. Extract a helper.

Dedicated Debt Sprints

Quarterly sprint focused entirely on debt. Works for larger items that can't be done incrementally.

Strangler Fig Pattern

For large architectural debt: build the new system alongside the old one. Route traffic gradually. Decommission old system when new one handles 100%.

Opportunistic Paydown

When a feature touches debt-heavy code, include the cleanup in the feature estimate. "This feature takes 3 days. If we also clean up the auth module while we're in there, it's 5 days, and every future auth change goes from 3 days to 1 day."

Tracking

Keep a living tech debt register (issue tracker, wiki, or dedicated file):

## Tech Debt Register

| ID | Item | Type | Impact | Risk | Effort | Status |
|----|------|------|--------|------|--------|--------|
| TD-001 | Auth module coupling | architecture | High | High | L | In Progress |
| TD-002 | Missing payment tests | testing | High | Medium | M | Scheduled Q2 |
| TD-003 | Node.js 16 → 20 | dependency | Medium | High | M | Backlog |

Review monthly. Update status. Celebrate paydowns.

Anti-Patterns

| Anti-Pattern | Problem | Fix | |-------------|---------|-----| | "Big rewrite" | Takes forever, ships nothing, fails | Incremental improvement, strangler fig | | Tracking without acting | List grows, nothing gets fixed | Reserve sprint capacity, enforce 20% rule | | Gold plating as debt paydown | "Refactoring" that's really over-engineering | Scope debt fixes tightly. Fix the problem, not the world. | | Only fixing debt when it breaks | Reactive, not proactive | Schedule regular paydown | | No business justification | Debt paydown gets deprioritized | Frame in business terms (cost, risk, speed) |

Utility Scripts

• scripts/debt_inventory.sh [directory] - Scan for TODO/FIXME/HACK/WORKAROUND/XXX/TEMP comments, files over 500 lines, and large functions. Groups by file with category counts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.