Connect the metaphor to an actual change cost
Describe the structural problem and the work it repeatedly complicates. A duplicated pricing rule can require coordinated edits in several modules; a tangled interface can make a small integration change risky. Record observed consequences rather than using the debt label as a substitute for an explanation.
Illustrative scenario: adding a new customer tier requires changing three separate eligibility calculations. The debt item is the duplicated policy boundary, while the extra coordination and inconsistent outcomes are its consequences. A bounded consolidation could address that cause if the existing differences are first understood and tested.
Distinguish debt from neighboring backlog work
A defect is incorrect behavior against a requirement, and a feature is a desired capability. Either may be related to debt, but they need their own acceptance conditions. A dependency nearing end of support adds an environmental constraint that should be documented explicitly instead of hidden inside general code quality work.
Debt can come from an intentional short-term tradeoff or from learning that the original design no longer fits. Discuss the choice and its current consequences without assuming blame. The useful decision is whether addressing the structure now is better than continuing to bear its effect on planned changes.
Decide when repayment is worthwhile
Prioritize debt in frequently changed, high-impact areas where the team can identify a realistic benefit. Compare the estimated intervention and risk with the work it is expected to enable. A rarely touched module may not justify a large cleanup even when its internal structure is unattractive.
Keep the proposed remedy specific: isolate a boundary, remove duplicated policy, or establish a test seam. Define evidence of improvement, such as one location for a rule change and stable behavior checks. Avoid claiming that a single sprint can remove all debt from a living system.
Working sheet
| Observation | Useful classification | Acceptance direction |
|---|---|---|
| Rule duplicated in three modules | Code/design debt | One clear policy boundary |
| Calculation violates requirement | Defect | Correct expected result |
| Requested export does not exist | Feature | New agreed capability |
| Runtime no longer supported | Support constraint with possible debt | Verified upgrade or replacement |
Questions about what is technical debt?
Is all technical debt bad?
A deliberate bounded tradeoff can be reasonable. Make its consequences and revisit conditions explicit rather than assuming every shortcut is permanent.
Can a team eliminate technical debt completely?
Design needs change as the team learns. Focus on managing consequential debt rather than claiming a permanently debt-free system.
How should I use the working sheet?
Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.
Sources and further reading
Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.
