Skip to content
Velloreth
Programming 10 min read

Technical Debt: How to Talk About It and Pay It Down

Technical debt in practice: what counts as debt, how to translate it into delivery risk non-engineers understand, and how to pay it down without a rewrite.

By

“Technical debt” gets used as an insult, an excuse, and a generic complaint about code someone does not like. That is why the conversation usually goes nowhere: engineers say “we have debt,” hear “the code is bad,” and leadership hears “we want to do unpaid work instead of shipping.”

The metaphor, when taken seriously, says something more useful. Debt is leverage. You borrowed speed to ship something that mattered, and like any loan it has interest — paid every time someone touches the borrowed-from code. The loan was probably correct. The failure mode is debt nobody recorded, nobody prices, and nobody plans to repay.

What is actually debt

Not every disliked file is debt. Sorting the categories changes the conversation, because each one has a different remedy:

KindWhat it isTypical remedy
Deliberate shortcutKnown shortcut taken to ship on timeSchedule repayment; it is a real loan
Accidental complexityMess from churn, unclear requirements, handoffsIncremental refactoring; no “creditor” to pay
Missing testsChanges here are guessworkCharacterization tests, then refactor
Outdated dependenciesUpgrade is a project because change was deferredContinuous small upgrades; budgeted migrations
Knowledge debtOnly one person understands a moduleDocs, pairing, deliberate handover
Platform driftFive ways to do the same thing across servicesConsolidate gradually; pick a winner

Notice the second row: accidental complexity is not debt in the strict sense — nobody chose it, and there is no agreed principal. But it behaves like debt anyway: it taxes every change. Arguing the taxonomy with your team is less useful than agreeing on the impact, which is measurable either way.

The other important distinction is debt versus rot. Debt is still serving its purpose — the module is slow to change but works. Rot is code that is actively wrong: known bugs nobody fixes, alerts everyone ignores, a build step nobody understands. Rot needs attention now; debt needs a plan.

Why “let us refactor” goes nowhere

Engineers often make the case badly, in ways that guarantee rejection:

  • Vague scope. “The payments module needs a cleanup” has no end condition, so it estimates as infinity and dies in triage.
  • Moral framing. “This is a mess” reads as blame — of the people who wrote it, who are in the room or are the ones approving the request.
  • No link to outcomes. Cleanliness is not a business result. Without one, the request competes against features with customers waiting.
  • The big-bang pitch. “We should rewrite it properly” asks for months with no revenue and enormous risk. Leadership’s instinct to refuse rewrites is usually correct.

The reframe that works: debt work is a delivery investment, presented like any other. Bounded scope, tied to a business event, with the cost of doing nothing stated plainly.

Translate the interest into business terms

Debt becomes fundable when its interest shows up in numbers the business already tracks:

Engineering symptomWhat it looks like upstream
High change-failure rateIncidents, rollbacks, pages at 2 a.m.
Long lead time on one module“This small feature will take two weeks”
Flaky, slow testsReleases delayed; confidence erodes
Onboarding takes monthsTeam cannot scale; hiring pays no dividend
One person holds all knowledgeBus factor; they cannot take leave
Every change touches the same fragile fileRoadmap items quietly blocked or descoped

Pick the one that is already hurting. If the last three features touching checkout each slipped, that history is your business case. If an outage postmortem already blamed the legacy module, you are not asking for anything new — you are asking to execute on a finding.

Concrete evidence beats adjectives every time:

# the one-pager, kept to one page
Where:        pricing rules (4,200 LOC, 0 tests, 3 production incidents YTD)
Why now:      Q3 subscription feature must modify pricing logic
Cost of now:  ~2 weeks, inside the feature's existing estimate
Cost of later: feature estimate doubles (last two pricing changes took 4+ weeks each)
Proposal:     extract rule evaluation behind an interface, add tests for current
              behavior first (characterization tests), migrate feature onto it
Not asking:   rewrite, migration off the current framework, touching anything else

Six lines, one module, a number attached, and an explicit “not asking” list. This document is the difference between a conversation and a plea.

How to run the conversation

With product and leadership:

  1. Lead with the shared goal. “The subscription feature needs to change pricing logic — here is what that costs today.”
  2. Offer options, not verdicts. A menu with tradeoffs (“do it fully inside the feature at +3 days”, “do it partially at +1 day and keep the risk”, “skip it and accept the same 4-week cost on the next two pricing changes”) makes them a decision-maker rather than a defendant.
  3. Scope it like a feature. Acceptance criteria, an estimate, and a definition of done. If the refactor cannot be described in those terms, it is not ready to be scheduled.
  4. Ask for the small test first. A bounded slice — one module, two weeks, one measurable outcome — is easier to approve than a program, and it generates the data for the next request.
  5. Accept partial funding. “Half of what I asked, applied to the worst part” is a win, not a defeat.

With fellow engineers:

  • Drop the doom. “Everything is terrible and will collapse” is unfalsifiable and breeds helplessness. Name specific failure modes and their likelihood.
  • Respect the original authors. Almost every “how did we end up with this” has the same answer: constraints you did not see. Assume the loan was reasonable; argue about the repayment plan.
  • Resist endless debt talk. A team that narrates debt in every retro and repays none of it becomes the thing leadership learned to tune out. Pair every complaint with a proposed slice.
  • Distinguish blocking from annoying. Annoying debt can live for years legitimately. Only blocking debt deserves escalation.

Paying it down: the three channels

1. Opportunistic repayment (boy scout rule, bounded). While a ticket already touches a module, leave it measurably better: extract the method you had to hold in your head, add the test around the branch you changed, delete the dead code you confirmed unused. The constraint that keeps this safe: no scope creep. Cleanup inside the diff, not a parallel refactor that expands the review.

2. Planned slices. Reserve a fixed, visible fraction of each iteration — a fifth is a common starting point — for named debt items, chosen from the inventory below. Fixed capacity prevents both “never any time” and “we are doing nothing but cleanup this quarter.”

3. Opportunistic-by-design: fold it into features. The highest-approval-rate pattern is debt work inside the estimate of a feature that depends on it: “We can build subscriptions on top of the current pricing code, or extract the rules first and build on that — extraction adds three days and removes an estimated two weeks from the next two pricing features.” You are not requesting separate funding; you are choosing an implementation strategy.

Avoid the rewrite reflex. Rewrites fail in a particular way: the old system keeps earning requirements nobody documented — the tax-exempt customer, the import format from 2022 — while the new one ships without them. If replacement is genuinely necessary, use the strangler pattern: build the new path alongside the old, route traffic gradually, and keep the old system as the safety net until the new one has proven itself on real load.

Keeping a ledger so it does not silently compound

Debt becomes unmanageable when it is invisible. Three lightweight practices:

Record deliberate debt at the moment you take it. In the ticket, not a wiki nobody reads:

Known shortcut (debt): retry logic duplicated in 3 handlers instead of shared middleware.
Why: launch date; shared middleware needs cross-team review.
Repayment trigger: next time a 4th retry case appears, or by 2026-12-01.
Ticket: PLAT-1180

The trigger is the important line. Debt with a repayment condition gets repaid; debt with only an intention gets compounded.

Keep an inventory that is scored, not just listed. For each item: how often it is hit, how much time it costs, and what the risk is if it fails. The matrix sorts itself — frequently-hit and time-costly rises to the top, and you stop debating taste. A realistic-looking inventory:

ItemHitTime costRisk if it failsScore
Pricing rules, no testsEvery pricing feature+1–2 weeks eachWrong invoicesHigh
Legacy auth SDKWeekly support tickets+2 days/quarterLogin outageHigh
Old admin UI, ugly but stableRarely touchedNone measurableLowDefer
Two logging librariesConstant annoyanceMinutesNoneOpportunistic

Look at row three: debt that is never hit and never costs anything can stay indefinitely, and saying so out loud is as valuable as escalating row one. An inventory that only ever argues for cleanup loses credibility; one that explicitly clears items not to touch earns the escalations.

Make debt visible in the same places as features. On the board, in the iteration plan, in the same one-pager format. If debt lives in Slack threads and hallway conversations, it will always lose to things that are properly written down.

When not to pay

Paying debt down is not automatically virtuous, and some loans should be left alone:

  • Stable code nobody will touch again. Interest only accrues when someone transacts. If a module is frozen, working, and isolated, its ugly internals cost nothing.
  • Refactors with no test safety net and no time to build one. Moving code you cannot verify is taking on new debt to repay old debt.
  • Churn for style. Renaming, reformatting, and re-organizing that changes no behavior and no reading experience is not repayment — it is a distraction with a PR attached.
  • During an active crisis. Debt work in an incident window competes with the incident. Write it down, schedule it after, and move on.

The correct question is never “should we eliminate technical debt” — that is like asking whether a business should stop borrowing entirely. It is: which loans are charging interest we can see, and is repayment the best use of the next slice of capacity? Some of the time, the honest answer is no, and knowing that is what makes the “yes” credible.

The part worth internalizing

Debt is a tool, not a stain: the team that never borrows ships slowly, the team that never records what it borrowed is surprised by the interest, and the team that treats every shortcut as a crisis never ships at all. The mature version of this skill is not writing perfect code — it is knowing what you are trading, writing it down, and choosing when to pay.

The next time someone says “we have technical debt,” the useful follow-up is not “how bad is it?” It is: what did we buy with it, what is it costing us now, and what is the smallest thing we can do about it this month?

Frequently asked questions

What is the difference between technical debt and bad code?
Debt is a known shortcut that bought speed, usually with a decision behind it — it is working software with a cost attached. Bad code is often just accidental complexity, unclear requirements, or code nobody has had the chance to improve. Both slow you down, but only one was a trade.
How do I convince leadership to spend time on tech debt?
Do not pitch the code; pitch the delivery impact. Pick one concrete cost — features blocked, incidents per month, time to make a change — propose a bounded fix with an estimate, and connect it to work already on the roadmap. Smaller, specific asks get approved far more often than blanket cleanup.
How much capacity should go to tech debt?
A common working pattern is a fixed minority of each iteration — often around a fifth — plus opportunistic cleanup inside feature tickets. The exact number matters less than making it consistent and visible instead of whatever is left over.
Should we rewrite instead of paying debt incrementally?
Rarely. Rewrites carry all the old requirements plus the ones nobody remembered, while features continue in parallel on the old system. Prefer incremental replacement — new path alongside old, traffic migrated gradually — unless the foundation genuinely cannot be extended.