Tagging tech debt so it actually gets paid

TL;DR - Tech debt was invisible: a few TODOs in the code and a lot of complaining. I gave it a label, a type and a link between the code and the issue. Now it shows up in planning with a cost attached, and it competes for sprint time like any other work.

Every dev on the team could name the worst parts of the code. None of that was written down anywhere useful. There were TODO comments with no owner, no date and no context. When I asked for “time for tech debt” in planning, I had no list to show and no way to say what it was costing us.

A label with a type

In GitLab I created one tech-debt label and a few type labels next to it:

• debt-security: outdated dependency with a CVE, secrets in the wrong place.
• debt-reliability: something that fails in production now and then.
• debt-speed: code that makes every change slow.
• debt-tooling: old build, old runtime, old libraries.

Each issue also answers two questions in the description: what hurts today, and what happens if we leave it for six months. That second answer is what gets it prioritized.

Linking the code to the issue

The TODOs became a pattern the team can grep:

// TECH-DEBT(PAT-1234): retry logic duplicated in three integrations

No issue number, no comment. A plain grep for TECH-DEBT( lists every known shortcut in the repo, and each one points to an issue that explains it. Reviewers ask for the issue when a new one shows up without it.

flowchart LR
  Code[TECH-DEBT comment in code] --> Issue[Issue with tech-debt label]
  Issue --> Board[Debt board by type]
  Board --> Sprint[Share of each sprint]
  Sprint --> Done[Fixed, comment removed]

Where the time comes from

I’d rather have a small, steady slice of every sprint for debt than a “debt sprint” every quarter, which always gets cancelled when a customer asks for something. The team picks from the board, starting with security and reliability.

What changed

Planning conversations got easier. Instead of “the code is bad”, I can point to an issue tagged reliability with the failures linked to it. That gets a yes much faster. The debt didn’t go to zero, and it won’t. But it stopped growing in the dark.