Technical Debt Management

Technical Debt Management (Verbose)

Core Patterns

The Debt Register

Debt that exists only in engineers' heads cannot be prioritised, funded, or argued for. A register makes it a portfolio of items with carrying costs.

The financial metaphor is load-bearing, so use it precisely:

• Principal — the one-off cost to fix it properly. An estimate in engineer-days, produced the same way you estimate features.
• Interest — the recurring cost of not fixing it. Extra effort per change in the affected area, plus incident cost, plus onboarding drag. This is the number that decides priority, and the one teams usually skip.
• Trigger — the condition that makes paydown due. Without one, every item stays "someday".

A complete entry:

DEBT-114 — Order totals recomputed in three places

Where: checkout/pricing.py:340-520, admin/order_edit.py:88-210, jobs/reconcile.py:55-190. Three implementations of discount stacking and tax rounding that have drifted apart.

How it happened: admin editing shipped under a deadline in 2024-03 and copied the checkout logic rather than extracting it; the reconciliation job copied the admin version a year later. Prudent-deliberate at step one, then reckless-inadvertent at step two.

Interest:

• Pricing rule changes cost 3 engineer-days instead of ~1. Six such changes in the last 12 months → **12 engineer-days/year**.
• 2 of the last 5 sev-2 billing incidents were caused by the three paths disagreeing. Direct incident cost ~6 engineer-days plus ~$40k in manual refund correction.
• New engineers take an extra half-day to learn which path is authoritative.

Principal: ~8 engineer-days. Extract a PricingEngine, run it in shadow mode against all three call sites for two weeks comparing outputs, then migrate and delete the duplicates.

Trigger: the Q3 multi-currency epic touches pricing. Pay down before it starts, or every ticket in that epic costs roughly triple and a fourth copy gets created.

Growth: interest rises with each new call site and each currency.

Owner: payments team. Reviewed: 2026-06-02.

The estimates need to be defensible, not exact. Derive interest from evidence you already have: git log frequency on the files, cycle time on tickets touching that area versus the team median, incidents tagged to the component, and the review comments where people ask "which one of these is real?".

Keep the register small — 15 to 30 live items. A register with 400 entries is a graveyard nobody reads, and the act of pruning it is itself a prioritisation.

Fowler's Quadrant, Applied

The four cells have genuinely different remedies, which is the whole reason to classify.

Prudent-deliberate is legitimate engineering. It is a loan taken knowingly to buy time-to-market. It only stays prudent if the register entry and the trigger are written at the moment of the decision — that is the difference between a loan and a default. In review: "fine, but the ticket and the trigger go in this PR description."

Prudent-inadvertent is what learning looks like and cannot be prevented by process. You did the reasonable thing with the knowledge available; the domain turned out to be shaped differently. The remedy is to refactor when the next change makes it cheap, not to hold a retrospective about it.

Reckless-deliberate is the dangerous cell, because it is a process failure wearing a technical costume. Somebody decided the schedule mattered more than the consequences. Fixing the code without fixing the pressure guarantees a repeat next quarter. The escalation is about capacity and dates, not about tests.

Reckless-inadvertent is a capability gap. Refactor tickets do not address it — pairing, review standards and design discussion do. Punishing it hides it; the code keeps arriving, just less visibly.

Two useful consequences. First, in a retro, arguing about which cell an item is in is time well spent, because it decides who acts. Second, a team whose register is mostly reckless-deliberate has a management problem, and no amount of refactoring budget will fix it.

Funding Paydown

The boy-scout rule is necessary and insufficient. "Always leave the code cleaner than you found it" handles debt at the scale of a confusing variable name, a missing test, or an extracted function. It cannot handle structural debt: nobody extracts a service, splits a 4,000-line module, or replaces an ORM opportunistically while fixing a bug. And they shouldn't — a bugfix PR carrying a large unrelated refactor is genuinely harder to review and riskier to roll back, so reviewers push back correctly, and the rule quietly caps itself at the trivial.

Structural paydown needs budget:

The percentage allocation is the usual default, and it works only with four rules enforced:

1. Paydown items live on the same board, estimated the same way, visible to the same stakeholders. Invisible work is unfundable work.
2. The allocation is protected during crunch. This is counterintuitive and non-negotiable: crunch is largely caused by debt, so suspending paydown during crunch guarantees more crunch. Suspend it once and it never returns.
3. Never schedule paydown last. Whatever is last in a sprint is what gets dropped. Put it first, and the feature work absorbs the overrun instead.
4. Every completed item reports the interest it removed. "Pricing changes now take 1 day, down from 3; two months of tickets confirm it." This is what buys the allocation for next quarter — without it, the budget is a matter of faith and will be cut by the first leader who doesn't share it.

When Not to Pay Debt Down

Refactoring only returns value through future changes to the code. If there are no future changes, the return is zero regardless of how bad the code is.

Do not pay down when:

• The code is scheduled for deletion or replacement within roughly two quarters. Refactoring something about to be deleted is pure loss.
• It is stable and untouched. One commit in three years, no incidents, no planned work. Ugly and quiet is not debt — it charges no interest. It may still be worth documenting so nobody "improves" it.
• Payback exceeds the remaining lifetime. A 20-day refactor saving 2 engineer-days/year on a system with 3 years left loses 14 days.
• The area is frozen for compliance or contractual reasons, so changes carry a recertification cost that dwarfs the interest.
• You cannot name the interest. If nobody can say what it costs per change, either the analysis hasn't been done or the item is aesthetic preference. Both mean: not yet.

A rough ranking function:

priority ≈ (interest_per_change × changes_per_year + incident_cost_per_year)
           / principal

Change frequency is the dominant term. Identical duplication in a file touched weekly and a file touched annually differ by roughly 50× in carrying cost. This is why "refactor the worst code" is the wrong instinct and "refactor the code you keep having to touch" is the right one. Overlaying git log change frequency on complexity metrics finds the real targets in about an hour.

Be equally clear about what is not debt: code you dislike stylistically, an older-but-working library with no CVEs, and a design you would do differently today but never need to change. Calling those debt inflates the register and devalues the entries that genuinely cost money.

Making the Cost Visible to Non-Engineers

Executives do not decline to fund debt paydown because they don't care about engineering. They decline because "the auth module is a mess" is not a decision-shaped input. Convert every item to their units: money, time, risk, delivery predictability.

The sentence that works is always the same shape: "This costs X per quarter and is growing. It costs Y once to stop it. It pays back in Z months." That is a capital allocation question, and capital allocation is a thing executives are good at.

Two amplifiers. Show the compounding curve for debt whose cost grows — dependency drift, migrations that get harder as data volume rises, coupling that worsens with each new caller. A flat cost is a trade-off; a rising cost is a deadline. And tie debt to delivery predictability, since that is usually what leadership feels most acutely: "the reason estimates in billing are unreliable is that every change touches three code paths" connects debt to something they were already unhappy about.

Finally, report paydown outcomes in the same units you used to request it. A quarterly line — "we spent 40 engineer-days on paydown and removed an estimated 90 days/year of recurring cost" — is what turns the allocation from an annual argument into a standing budget line.

Common Anti-Patterns

❌ A debt backlog with no estimates and no interest figures. It is a list of complaints; nothing on it can be prioritised against a feature. ✅ Every entry carries principal, interest, trigger and owner.

❌ "We'll clean it up after launch" with no ticket. Post-launch capacity goes to post-launch problems, and the debt becomes permanent and undocumented. ✅ The register entry and trigger are written in the same PR that takes on the debt.

❌ Relying on the boy-scout rule for structural debt. It caps out at renaming things, and large refactors in bugfix PRs get rejected in review — correctly. ✅ Budget an explicit, protected allocation for structural items.

❌ Cutting the paydown allocation when the schedule slips. Debt is a major cause of the slip, so this accelerates the problem. ✅ Protect the allocation precisely when pressure is highest.

❌ Refactoring the ugliest code rather than the most-changed code. Carrying cost is interest × frequency, and frequency dominates. ✅ Rank with change frequency from git log overlaid on the register.

❌ Proposing a rewrite instead of incremental paydown. Rewrites re-derive years of undocumented behaviour, and the old system keeps changing underneath. ✅ Strangle incrementally with measurable checkpoints and shadow comparison.

❌ Arguing debt on aesthetics or "best practice". Nobody outside the team can evaluate the claim, so it loses to anything with a number. ✅ Argue in engineer-days, incidents, change failure rate and CVEs.

❌ Fixing reckless-deliberate debt without addressing the schedule pressure. The same pressure produces the same debt next quarter. ✅ Escalate the process cause; treat repeat recklessness as a capacity problem.

❌ Refactoring a module that is being replaced next quarter. All cost, no return. ✅ Check remaining lifetime before scheduling any paydown.

❌ Never reporting what paydown achieved. The budget survives on goodwill and dies with the next reorg. ✅ Publish removed interest per item in the same units used to request funding.

Technical Debt Checklist

• A register exists, is under ~30 live items, and is reviewed quarterly
• Each entry names what, where, principal, interest, trigger and owner
• Interest is derived from evidence (change frequency, cycle time, incidents), not intuition
• Each item classified in Fowler's quadrant, with the remedy matched to the cell
• Prudent-deliberate debt gets its register entry at the moment of the decision
• Recurring reckless-deliberate debt escalated as a process and capacity issue
• An explicit paydown allocation exists (typically 15–20% of capacity)
• The allocation is protected during crunch and is never the last item in the sprint
• Paydown items sit on the same board and are estimated like features
• Items ranked by interest × change frequency ÷ principal, not by how bad the code looks
• Remaining lifetime checked before scheduling paydown; doomed code left alone
• Stable, untouched, unlovely code explicitly excluded from the register
• Compounding items flagged with their growth curve
• Each item translated into money, risk, or delivery predictability for funders
• Large paydown done incrementally with shadow comparison, not as a rewrite
• Removed interest measured and reported after each completed item