Technical Debt

When an engineer says "the code is messy, so this will take a while," it sounds like an excuse to anyone who doesn't read code. The same engineer shipped something comparable in two days last month, and there was no vocabulary for explaining why this month's version needs two weeks.

Planning meetings kept jamming in the same spot. Engineering would ask for time to clean things up, and someone would ask what the customer gets out of that. The honest answer — nothing, not right away — sent the work to the bottom of the list every time, and every postponement made the next piece of work a little slower.

Framing it as debt filled that gap. There's a principal and there's interest, and if you don't pay it down the interest keeps going out. Once the conversation moved into that shape, engineers and the people holding the budget were finally using the same language. "If we don't clean this up, everything we build here runs about 20 percent slower" is something a person can make a decision about. "The code is messy" isn't.

The principal is the postponed cleanup itself: code copied and pasted under deadline, a file left as one lump because splitting it could wait, config nobody uses and nobody feels safe deleting. Individually none of it seems worth stopping for, which is exactly why it accumulates.

The interest is the extra time the state costs on every subsequent piece of work. It never arrives as a single bill — it comes out in slivers spread across everything.

• The same value lives in three places, so every change means finding and editing all three. Miss one and that's next week's incident.
• Nobody knows what breaks when you touch this area, so verification alone eats half a day.
• A new hire needs two days to understand this part of the system. In a tidy area it would be two hours.

The invisibility of that interest is the point of the concept. It's also why teams misdiagnose themselves as understaffed. Hiring more people doesn't help as much as expected, because the new people pay the same interest on every task.

You pay the principal down by refactoring — changing the structure while leaving behaviour exactly as it is. Nothing visible changes on screen, so the only way to see the result is whether similar work gets faster afterwards.

Not all of it is a mistake, though. Sometimes a team borrows deliberately. If the investor demo is in two weeks and doing it properly takes six, the temporary version is the right call. What makes it borrowing rather than negligence is writing down what was borrowed. Writing it down means recording what and when — "the billing screen is a temporary structure, clean it up within two weeks of the demo" — rather than noting that something is rough. The dangerous kind is the debt nobody knew they took on.

Mostly in schedule negotiations. "We're spending 20 percent of this quarter paying down debt instead of shipping features" is the sentence this concept exists to make sayable. It only lands if it comes with what gets faster in return; "we need to clean things up" still loses. "Two weeks on the billing module now, and every billing change after that costs us a day less" is the version the other side can actually weigh.

In a retrospective — the session at the end of a cycle where a team reviews what went well and what got stuck — it's used to name the cause of a slowdown. When estimates keep missing in the same area, that area's debt is the first suspect. "Anything touching billing takes twice as long" is an observation that turns into a repayment candidate.

It also shows up in code review, where another engineer reads a proposed change and comments on it, as the word that settles whether to fix something now or later. When someone decides the structure is awkward but out of scope for this change, the decision has to become a tracked item on the spot. Otherwise nobody remembers, and six months later all that's left is a slow area with no known cause.

"Let's leave this as tech debt and just open a ticket."

We're not fixing it properly now, but we're recording it so it isn't forgotten.

"We're slow because of debt, not because we're short-staffed."

Adding people won't fix this, because every new engineer pays the same interest on every task.

"This one's deliberate debt. We pay it back right after the demo."

Not a mistake — a choice made to hit a date.

At Pagedeck, Theo said the same thing every time he opened the billing module. The structure had been bolted together in a hurry early on, nobody had ever tidied it, and three features had since been stacked on top, so even a small change meant checking far too many places. When Grace set aside part of the next quarter for repayment, Theo made a list of what to pay down first. Not a list of everything — a list starting with the parts the team was going to keep touching.

Plenty of people read it as another name for bad code. Both end in "hard to change," so the two look identical from outside. But debt taken knowingly and debt accumulated unknowingly are handled differently. The first is already visible, so you plan the repayment. The second has to be surfaced before anything else can happen, because nobody knows what's in there. Collapse the two and the conversation ends at "our codebase is a mess" instead of reaching a repayment plan.

The other misreading is that all of it has to be paid off. It's a debt, so surely you clear it. But debt in an area nobody will touch again charges no interest. Spending two weeks tidying a screen you're about to delete isn't repayment, it's waste. The parts worth paying down are the parts you keep changing, and a team that sets out to clear everything runs out of time before it reaches the expensive ones.