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 Velloreth
“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:
| Kind | What it is | Typical remedy |
|---|---|---|
| Deliberate shortcut | Known shortcut taken to ship on time | Schedule repayment; it is a real loan |
| Accidental complexity | Mess from churn, unclear requirements, handoffs | Incremental refactoring; no “creditor” to pay |
| Missing tests | Changes here are guesswork | Characterization tests, then refactor |
| Outdated dependencies | Upgrade is a project because change was deferred | Continuous small upgrades; budgeted migrations |
| Knowledge debt | Only one person understands a module | Docs, pairing, deliberate handover |
| Platform drift | Five ways to do the same thing across services | Consolidate 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 symptom | What it looks like upstream |
|---|---|
| High change-failure rate | Incidents, rollbacks, pages at 2 a.m. |
| Long lead time on one module | “This small feature will take two weeks” |
| Flaky, slow tests | Releases delayed; confidence erodes |
| Onboarding takes months | Team cannot scale; hiring pays no dividend |
| One person holds all knowledge | Bus factor; they cannot take leave |
| Every change touches the same fragile file | Roadmap 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:
- Lead with the shared goal. “The subscription feature needs to change pricing logic — here is what that costs today.”
- 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.
- 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.
- 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.
- 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:
| Item | Hit | Time cost | Risk if it fails | Score |
|---|---|---|---|---|
| Pricing rules, no tests | Every pricing feature | +1–2 weeks each | Wrong invoices | High |
| Legacy auth SDK | Weekly support tickets | +2 days/quarter | Login outage | High |
| Old admin UI, ugly but stable | Rarely touched | None measurable | Low | Defer |
| Two logging libraries | Constant annoyance | Minutes | None | Opportunistic |
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?