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

Debt and adjacent work
ObservationUseful classificationAcceptance direction
Rule duplicated in three modulesCode/design debtOne clear policy boundary
Calculation violates requirementDefectCorrect expected result
Requested export does not existFeatureNew agreed capability
Runtime no longer supportedSupport constraint with possible debtVerified upgrade or replacement
Download this worksheet (CSV)

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.

Make the next change verifiable.

Getzilla is an open source workflow for changes to existing repositories. Inspect the project, define acceptance checks, and keep independent review in the loop.

See the repository workflow See current access and pricing