Make invisible costs visible
Technical debt that lives only in engineers’ heads never gets paid down — it just slows everything until a rewrite feels like the only option. A registry turns vague unease into a concrete, prioritized list that product and engineering can plan against. By scoring each item’s impact and effort, you can finally sequence debt work alongside features instead of pretending it does not exist.
How it works
Each row captures a debt item: a short name, the affected area, an impact description, an impact rating, an effort-to-fix rating, and an owner. Impact and effort are rated low, medium, or high. The tool derives a priority from the pair using an impact-versus-effort heuristic: high impact with low effort is a quick win and ranks top; high impact with high effort is important but needs planning; low impact ranks bottom regardless of effort.
The registry exports as a Markdown table sorted by derived priority, so the most valuable, cheapest fixes float to the top of your backlog review. The priority labels give product and engineering a shared language for deciding what to tackle and what to defer.
The priority matrix explained
| Impact | Effort | Derived priority | What to do |
|---|---|---|---|
| High | Low | P1 — Quick win | Schedule in next sprint |
| High | High | P2 — Important, plan it | Dedicate a project or sprint |
| Medium | Low | P3 — Opportunistic | Fix when touching that area |
| Medium | High | P4 — Reconsider | Defer unless it blocks growth |
| Low | Any | P5 — Backlog | Accept it or delete the entry |
The matrix prevents two common failure modes: teams that only tackle easy debt (lots of low-impact cleanup that looks productive but changes nothing important), and teams that let high-impact debt fester because the effort to fix it is high and nobody has argued for dedicated time.
Writing effective impact descriptions
Impact descriptions are the most important field in the registry. A good description answers: “What would a non-engineer understand as the consequence of leaving this unfixed?” Compare:
- Weak: “The auth module is messy.”
- Strong: “Access tokens never expire. A leaked token gives an attacker permanent access until we manually revoke it from the database.”
The strong version makes the business consequence clear. Product owners who read “messy” skip the item; product owners who read “permanent attacker access” schedule it.
Similarly for lower-impact debt:
- Weak: “Variable names in utils.js are confusing.”
- Strong: “New engineers spend 30–60 minutes understanding the utils.js naming convention, which slows onboarding but does not affect production behaviour.”
The second version still reads as low impact but provides honest context for why it stays at the bottom of the list.
Tips and example
Keep impact descriptions concrete and tied to consequences. A high-impact, low-effort item like “Add the missing index causing the slow dashboard query” should jump the queue because it is cheap to fix and directly improves user experience. Re-rate items as reality shifts — debt that was low impact can become high the moment that area becomes a hot path in a new feature. Assign one named owner per item; unowned debt never gets fixed.