A Way to Prioritize Technical Debt That Isn't Just Vibes

A refactor proposal that can't say what it prevents or what it speeds up is competing against a feature that has a customer's name on it, and it will keep losing that fight, deservedly, no matter how strongly the team feels about it. The fix isn't a better pitch, it's a better proposal.

Name the specific incidents, slowdowns, or onboarding friction the debt has already caused, not the abstract principle that clean code is good. "This module caused three production incidents last quarter and adds a day to every new hire's ramp-up" gets funded. "This code is messy" doesn't.

Age is the easiest thing to measure about a piece of debt and the least useful one. Score instead on how often it actually causes pain, how many engineers it slows down each time, and how much of the system would break if it failed outright.

A five-year-old module nobody touches ranks below a six-month-old one that causes a support ticket every week, even though the instinct is to worry about the older code first just because it's been sitting there longer. Old and quiet is a very different problem from new and constantly painful.

Write the score down somewhere the whole team can see, not just in one engineer's head. A shared, visible ranking turns an argument about feelings into a conversation about the specific numbers behind two competing items, and it means the ranking survives past the one person who happened to build it.

Score each debt item on the pain it actually causes, using these criteria:

• How often the item causes pain in practice, rather than how old it is.
• How many engineers it slows down each time it bites.
• Whether it sits directly in the deploy path, such as a slow or flaky test suite.
• What it has cost you recently in incidents, wasted engineering hours or onboarding friction for new hires.

Some debt is contained: a messy but rarely touched corner of the codebase that costs nothing until someone finally has to work in it. Other debt sits directly in the deploy path, a slow, flaky test suite, a manual step nobody automated, and taxes every single release regardless of what's being shipped.

That second category deserves priority even when its blast radius looks small in isolation, because its actual cost is multiplied by how often the team deploys, not by how often the code itself changes. A flaky test that adds ten minutes to every deploy costs far more over a quarter than a messy module nobody has opened in months.

Dedicated debt sprints tend to get canceled the first time a deadline slips, because they're the easiest thing on the calendar to defer when a launch date is at risk. A steadier approach reserves a fixed, modest share of each engineer's time, and holds that allocation even when a big feature push is underway.

Treat it as a standing operating cost rather than a discretionary extra, the same way you wouldn't skip a month of server bills to fund a feature push. The debt keeps compounding whether or not anyone's watching, and a standing allocation is what actually keeps up with it.

A full rewrite is almost always the wrong answer, and teams reach for it anyway because incremental fixes feel slower than starting fresh, even when they aren't. Reserve a rewrite for the rare case where the current design is fundamentally wrong for what the system now needs to do, not just tired from years of patches.

And only start one where you can name a concrete stopping point in advance, instead of an open-ended project that competes with every future roadmap item indefinitely and rarely finishes on the timeline anyone originally imagined.

A debt list scored once and never revisited drifts out of date the same way a roadmap does. An item that ranked low six months ago because it rarely got touched can become urgent within a quarter once a new feature starts routing through it constantly.

Revisit the scores on a fixed schedule, quarterly is reasonable for most teams, rather than only when someone happens to remember the list exists. The review itself doesn't need to be long: for each item, ask whether the frequency of pain has changed since it was last scored, and reorder the list accordingly.