# Technical Debt Walkthrough — Learn by Doing

## Step 1: Recognize the Metaphor

Debt has principal and interest. So does tech debt.

**Task:** Pick a piece of code in a project you know (or imagine one) that's hard to change. Estimate: (a) how long to fix it properly (principal), and (b) how much extra time each change in that area costs (interest per touch).

**Question:** If you touch this code 10 times a year, is the total interest more or less than the principal? When does it become worth paying down?

**Checkpoint:** The user can distinguish principal (one-time fix) from interest (recurring cost). They recognize that high-touch code has higher interest.

---

## Step 2: Place Debt in the Quadrant

Fowler's quadrant: deliberate vs inadvertent, prudent vs reckless.

**Task:** For each scenario, place it in the quadrant and explain why:
1. Team ships without tests to hit a deadline, plans to add tests next sprint
2. Junior dev writes a 500-line function; doesn't know better
3. Team chooses a quick prototype that becomes production; never refactors

**Question:** Which scenario is "prudent deliberate"? Which is "reckless deliberate"? Why does the distinction matter for how you talk about it?

**Checkpoint:** (1) Prudent-deliberate if they actually add tests. (2) Prudent-inadvertent (didn't know). (3) Reckless-deliberate (knew but never paid). The user can explain the quadrant.

---

## Step 3: Identify Code Smells

Smells are signals, not proof — but they point to debt.

**Task:** Look at a file in your codebase (or a sample online). List at least 3 potential smells: long functions, duplication, deep nesting, unclear names, etc.

**Question:** Why is each a "smell" rather than necessarily bad? What would you need to verify before calling it debt?

**Checkpoint:** The user lists concrete smells and understands they're indicators. They recognize that some "smells" might be acceptable in context (e.g., a simple 100-line script).

---

## Step 4: Measure What Matters

Different metrics reveal different aspects of debt.

**Task:** For a hypothetical module that keeps having bugs: what metrics would you collect to make a case for paying down debt? List at least 3.

**Question:** How would you explain "cyclomatic complexity" or "churn" to a non-technical stakeholder? What's the business impact?

**Checkpoint:** The user suggests metrics like: bug count by module, complexity, files changed per feature, cycle time. They can translate at least one into business impact (e.g., "slows releases by X%").

---

## Step 5: Prioritize Paydown

Not all debt is equal. Prioritize by interest and risk.

**Task:** You have three debt items:
- A: Rarely touched, ugly code (principal: 2 days)
- B: Touched every sprint, moderate mess (principal: 5 days, interest: 1 day/sprint)
- C: Security concern in auth module (principal: 3 days)

Order them by paydown priority and explain your reasoning.

**Question:** When might you fix A before B? When would C always come first?

**Checkpoint:** User likely orders C first (risk), then B (high interest), then A (low interest). They can articulate when risk trumps interest.

---

## Step 6: Communicate to a Manager

Stakeholders need outcomes, not jargon.

**Task:** Write a 2–3 sentence pitch to your manager for paying down debt in module X. Include: what's wrong, what it costs now, what fixing it would unlock, and a simple ask (e.g., "1 sprint").

**Question:** What would make a manager say yes? What would make them say "we can't afford it"?

**Checkpoint:** The user's pitch uses business language (time, risk, roadmap), not just "code quality." They have a concrete ask.

---

## Step 7: Choose Refactor vs Rewrite

Different situations need different strategies.

**Task:** For each scenario, choose Refactor or Rewrite and justify in one sentence:
1. 50-line function doing 4 things
2. Legacy monolith, 10 years old, no tests, wrong architecture
3. New feature needs different data model; current one is workable but awkward

**Question:** What's the main risk of a full rewrite? When is "strangler fig" better?

**Checkpoint:** (1) Refactor — extract functions. (2) Often rewrite or strangler — but strangler is safer. (3) Refactor or incremental migration. User understands rewrite is risky and refactor is usually preferable.