Technical Debt Management: A Practical Framework

Your roadmap says the checkout-api migration will take six weeks. Two weeks in, your engineers are still untangling a shared pricing module that nobody owns, the test suite takes 48 minutes, and the estimate has doubled. The debt was always there. What failed was its management: no owner, no exposure estimate, and no trigger for acting before the roadmap hit it.

I’ve seen this pattern in organizations with thousands of neatly tagged technical-debt tickets. The inventory looks disciplined. The roadmap still gets surprised. A backlog can tell you that imperfect code exists, but it cannot tell you which imperfection threatens the next product bet, which liability can wait, or which system should be retired instead of repaired.

My rule is simple: manage technical debtTechnical debtA design or implementation liability that makes a plausible future software change costlier, riskier, or impossible. as a portfolio of contingent liabilities. Do not promise to eliminate it. Make each material liability visible, price it against a plausible change, choose a treatment, and name the event that forces you to decide again.

The operating companion, Technical Debt Portfolio Reviews: Stop Re-Scoring, Start Deciding, shows how to reopen those decisions when assumptions change without imposing one meeting format.

Stop calling every imperfection debt

The term becomes useless when it covers every code smell, missing test, old dependency, defect, and unpopular design choice. You end up with a giant cleanup queue where a duplicated helper competes with an unsupported database and a stalled identity migration. Priority labels do not repair that category error.

The SEI’s 2024 technical-debt recommendations use a tighter definition: a design or implementation construct that is expedient now but can make a future change costlier or impossible. The future change matters. A messy module that nobody expects to touch may be ugly without creating material interest. A cleaner module on the critical path of a quarterly roadmap can be a larger liability.

Static analysis still has a role. ISO/IEC 5055:2021 on automated source-code quality measures defines repeatable measures for architectural and coding weaknesses associated with operational risk or excessive cost. Those findings are signals. They are not portfolio decisions because the scanner does not know your product roadmap, change probability, contractual exposure, or retirement plan.

Record a debt item only when you can answer two questions:

1. What concrete artifact, decision, or constraint creates the liability?
2. What plausible change becomes slower, riskier, or impossible because it exists?

If you cannot answer both, keep the finding in the engineering system that produced it. Do not promote it into an executive debt portfolio yet. This filter cuts noise and forces a connection to delivery.

Price the liability without pretending it is accounting

Financial language tempts you to invent precise numbers. Resist it. A four-week repayment estimate is uncertain, and future interest depends on whether the affected area changes at all. The goal is not a balance sheet. The goal is a comparable decision record with enough evidence to expose assumptions.

I use six fields:

Field	Decision question	Practical evidence
Artifact	Where does the debt live?	Repository, service, module, pipeline, platform, or dependency
Principal	What would repayment cost now?	A bounded estimate such as 3–5 engineer-weeks
Interest	What extra cost appears when you change it?	Rework, test delay, incident exposure, manual release steps
Probability	How likely is the affected area to change?	Committed roadmap, change frequency, support deadline
Exposure	What business outcome is at risk?	Revenue milestone, reliability target, compliance date, customer promise
Confidence	How reliable are these estimates?	High, medium, or low, with the missing evidence named

This is where the portfolio view earns its keep. Georgios Digkas and colleagues treat technical-debt interest as a risk combining the probability that an artifact changes with the extra cost incurred when it does. Their case study on interest-generation risk makes the practical point: a legacy module that changes often can deserve remediation before an equally weak module that rarely moves.

Consider checkout-api. Its Java 17 migration is blocked by pricing-shared@4.7.2, a library coupled to an abandoned rules engine. Repayment is estimated at four to six engineer-weeks. Every checkout change adds two days of integration testing, and the Q4 roadmap commits to country-specific pricing. Confidence is medium because nobody has yet separated the rules engine from the library in a staging branch.

That record is imperfect. It is also enough to debate against the roadmap. “The architecture is bad” is not.

Choose a treatment, not a priority label

Most debt backlogs offer variants of high, medium, and low. That delays the actual decision. Before ranking the item, choose what you intend to do with it.

Treatment	Use it when	Required commitment
Repay	Expected interest and exposure exceed the cost of removal	Fund the work, owner, completion condition, and validation plan
Contain	Full repayment is too expensive but interest can be bounded	Add an interface, test harness, wrapper, control, or migration boundary
Tolerate	Exposure is low or the triggering change is unlikely	Record the assumption, owner, expiry, and review trigger
Retire	The asset’s remaining value does not justify repair	Fund decommissioning and remove dependent roadmap promises

This prevents a common waste: polishing an asset that should die. I’ve watched six months of refactoring disappear when a product line closed soon afterward. The code improved. The investment decision did not.

Intentional debt can also be rational. Shipping a narrow implementation to test product demand may create a liability whose short-term return exceeds its expected interest. The decision becomes negligent only when the original assumption expires and nobody reopens it. Tolerance without an expiry is abandonment with better vocabulary.

For checkout-api, containment may beat immediate repayment. Your engineers could put a stable pricing contract around pricing-shared@4.7.2, add contract tests, and stop new consumers while the Q4 launch proceeds. Full repayment starts if a second market needs a different pricing model. You have reduced near-term exposure without pretending the underlying debt vanished.

Put the trigger into the roadmap

A fixed rule such as “reserve 20% of every sprint for debt” is easy to explain and hard to defend. It can fund low-value cleanup while a migration deadline approaches untouched. Capacity should follow exposure, not a ritual percentage.

Use triggers that connect the debt record to real decisions:

• a roadmap item enters committed planning;
• change frequency crosses an agreed threshold;
• measured rework exceeds the containment cost;
• a dependency reaches end of support;
• an ownership, reliability, or regulatory assumption expires.

Each trigger needs an owner with authority to reopen funding and scope. “Platform” is not an owner. Name the accountable person, the forum where the item returns, and the evidence required for the next choice. Without that mechanism, a review date is just another notification people dismiss.

The trigger also changes planning conversations. When country-specific pricing enters committed planning, the pricing-shared@4.7.2 record appears beside feature scope and staffing. You can fund repayment, narrow the product promise, accept a dated risk, or retire the old path. The trade-off is visible before delivery starts.

Measure interest that actually appears

The cleanest executive dashboard is often the least useful. A single debt ratio blends unrelated liabilities, hides uncertainty, and encourages local score optimization. The SEISoftware Engineering InstituteA Carnegie Mellon University research center that develops evidence-based practices for software engineering, architecture, cybersecurity, and technical debt management. reports that Google explored 117 candidate metrics against engineer-reported debt categories and found that no single metric predicted those categories.

Measure realized interest instead. Track how much unplanned rework a debt item caused, how often it delayed a change, whether it contributed to an incident, and whether its assumptions expired without review. Pair those outcomes with flow measures such as elapsed delivery time and repeat work. DORA’s continuous-delivery guidance recommends value-stream mapping for exposing bottlenecks, wait time, and work sent back because it was incomplete or incorrect.

The research gives you scale, not a universal target. Terese Besker, Antonio Martini, and Jan Bosch reported an average 23% of development time lost to technical-debt consequences in their 2018 longitudinal study. Their 2019 replication and extension, based on 258 survey responses and 32 follow-up interviews, produced a perception-based estimate of 36%. Do not paste either figure into your business case. Establish your own baseline around the liabilities connected to your roadmap.

Automation can collect evidence, but it cannot own the trade-off. A 2024 systematic mapping of technical-debt automation selected 178 studies and catalogued 121 tools, plugins, scripts, and bots. That breadth is useful for detection and measurement. It does not tell you whether checkout-api should be repaired, contained, tolerated, or retired.

Conclusion: make debt a decision system, not a backlog

Technical debt is not a problem of visibility. Most organizations already see it. The failure is structural: debt is recorded without being made actionable.

A backlog tells you what is imperfect. A portfolio tells you what matters, when, and why.

The difference is decision design.

When you treat technical debt as a portfolio of contingent liabilities, three shifts happen:

• You stop debating whether something is “real debt” and start asking what future change it affects.
• You stop optimizing for cleanup volume and start optimizing for exposure reduction.
• You stop assigning priority and start assigning treatment and ownership.

In practice, this means every meaningful debt item must answer four questions:

1. What future change does this constrain?
2. What is the cost of that constraint?
3. What treatment are we applying right now?
4. What event will force us to revisit this decision?

If you cannot answer these, you do not have a debt strategy—you have a list of complaints.

The checkout-api example is not unusual. Most systems do not fail because teams ignore problems. They fail because no one defines when a known problem becomes a decision.

Debt does not need to be eliminated to be under control. It needs to be governed.

And governance, in this context, is simple:

• make it visible in the language of change,
• price it in terms of future friction,
• assign ownership with authority,
• and bind it to real delivery triggers.

Everything else is inventory.