Write an item that a maintainer can verify
Use a concrete statement such as “discount calculation differs between checkout and renewal” rather than “checkout is messy.” Link the affected code, a failed test or a recent incident in your team’s own register.
Keep evidence separate from the proposed solution. The same symptom may have several causes. An investigation item should say what uncertainty it will resolve before somebody commits to an expensive rewrite.
Add the fields that make a decision possible
Extend the working sheet with an owner, status, effort range and revisit trigger when your team needs them. Include a bounded scope and explicit exclusions so the repair can be reviewed against a stable agreement.
For prioritisation, record both impact and frequency. A severe but unlikely failure and an everyday delay need different discussion. Do not multiply arbitrary scores and present the result as a measured monetary value.
Keep accepted debt visible
Use statuses such as investigate, planned, in progress, accepted and closed. Close an item only when the acceptance evidence exists. Link the final commit or operational check to the original problem.
An accepted item stays in the register with its decision owner and revisit trigger. Review it when the product enters the affected area, a dependency loses support or observed harm changes. A register without decisions is only an inventory.
Working sheet
| Problem and evidence | Bounded repair | Acceptance check |
|---|---|---|
| Checkout and renewal apply discounts differently; compare fixture totals | Extract the shared calculation; leave UI unchanged | Both recorded totals and boundary cases match |
| Import retries create duplicate fixture records | Add idempotency at the import boundary | Repeated fixture produces one logical record |
| Release smoke check depends on a shared test account | Create isolated test data for that journey | Two parallel runs complete independently |
| Critical module has no clear reviewer | Assign owner and document its public contract | A second maintainer reproduces the documented checks |
Questions about technical debt register template
Can we add cost estimates?
Yes, if the source and assumptions are visible. Use effort ranges and distinguish an observed recurring cost from a guessed future cost. Do not imply false precision.
How much detail belongs in one row?
Enough to decide and verify: evidence, impact, bounded action and acceptance check. Link longer incident notes or design documents rather than copying them into every cell.
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.
