# Technical Debt — Identifying, Measuring, and Paying It Down

<!-- hint:slides topic="Technical debt: Fowler's quadrant, principal vs interest, identification signals, measurement, and paydown strategies" slides="5" -->

## What Technical Debt Is (and Isn't)

**Technical debt** is the implied cost of rework caused by choosing a quicker or easier solution now instead of a better one that would take longer. Like financial debt: you get something now, you pay interest (extra effort) later.

It isn't:
- **Bugs** — bugs are defects; debt is structural
- **Missing features** — that's scope, not debt
- **"Bad code"** without a decision — debt implies a choice (even if unconscious)

## The Debt Metaphor

| Term | Meaning |
|------|---------|
| **Principal** | The work to fix the suboptimal design |
| **Interest** | Extra cost of every change that touches the debt (slower dev, more bugs) |

Low-touch code may have low interest; high-touch code has high interest. Pay down high-interest debt first.

## Fowler's Technical Debt Quadrant

Not all debt is equal. Martin Fowler divides it by **deliberate vs inadvertent** and **prudent vs reckless**:

```mermaid
flowchart LR
    subgraph Reckless["Reckless"]
        A1["Inadvertent: We didn't know better"]
        A2["Deliberate: We knew but cut corners"]
    end
    subgraph Prudent["Prudent"]
        B1["Inadvertent: We learned; design should change"]
        B2["Deliberate: Thoughtful tradeoff — plan to pay"]
    end
```

| | Reckless | Prudent |
|--|----------|---------|
| **Deliberate** | "We know we're cutting corners" — often a mistake; interest compounds | "We ship now, plan to fix" — acceptable if you actually pay it |
| **Inadvertent** | "We didn't know better" — inexperience, learning | "We learned; design should change" — inevitable, even for good teams |

**Prudent-deliberate** is the only "good" debt: you choose it knowingly and plan paydown. The rest range from unavoidable (prudent-inadvertent) to harmful (reckless-deliberate).

## Identifying Technical Debt

### Code Smells
- Long methods, deep nesting
- Duplication (DRY violations)
- Shotgun surgery (one change touches many files)
- Feature envy, God classes
- Comments that explain bad names instead of fixing them

### Velocity Trends
- Story points per sprint dropping
- Same-size features taking longer
- More bugs per release

### Bug Clusters
- Same module keeps failing — often a sign of structural debt

## Measuring It

| Metric | What It Tells You |
|--------|-------------------|
| Cyclomatic complexity | Per-function complexity; high = hard to test |
| Test coverage | Gaps indicate risky areas |
| Lead time / cycle time | How long from idea to ship |
| Bug rate by module | Where debt causes the most pain |
| Churn (files changed often) | High churn + high complexity = high interest |

## Prioritizing Paydown

1. **Interest rate** — How much does this slow us down? Fix high-touch debt first.
2. **Principal size** — Can we pay it in one sprint or does it need a plan?
3. **Risk** — Does it cause outages or security issues?
4. **Strategic fit** — Are we about to change this area anyway?

## Communicating to Stakeholders

- **Speak in outcomes** — "This slows feature X by 2 days per release" not "our code is messy"
- **Quantify when possible** — "We spend 20% of sprint on workarounds"
- **Offer options** — "We can pay 1 sprint now or absorb 3x cost over 6 months"
- **Tie to business goals** — "Fixing this unblocks the Q3 roadmap"

## Strategies for Paydown

### Boy Scout Rule
Leave code better than you found it. Small, incremental improvement.

### Dedicated Sprints
Allocate a portion of capacity (e.g., 20%) to debt paydown. Protects against infinite postponement.

### Strangler Fig
Replace a legacy system gradually by routing new behavior to new code and migrating callers over time. Avoids big-bang rewrites.

### When to Refactor vs Rewrite
- **Refactor** when the design is salvageable — extract, rename, split. Cheaper, lower risk.
- **Rewrite** when the design is fundamentally wrong, or the system is small enough that rewrite is faster than untangling. Rare; usually refactor.

---

## Key Takeaways

1. Debt = principal (fix cost) + interest (ongoing cost)
2. Quadrant: prudent-deliberate is acceptable; reckless-deliberate is toxic
3. Identify via smells, velocity, bug clusters
4. Measure and prioritize by interest and risk
5. Communicate in business terms; offer clear options
6. Prefer incremental paydown (boy scout, strangler fig) over rewrites