Tech Debt Ticket

Cleanup used to live entirely in conversation between engineers. That this file is frightening to touch, or that the deploy process takes far too long, came up over lunch and never reached the list of things the team planned to build.

Work that isn't on the list doesn't appear in a prioritization meeting. So the same quarter would commit to twelve features and zero cleanup, over and over. Deferred cleanup that piles up and takes time back later is technical debt, and it accumulates quietly until it surfaces in estimates. Work that took a week six months ago now gets quoted at three, and there was nowhere in the process to explain the difference.

A tech debt ticket pulls that work up onto the list. Written down, it reaches the meeting where order gets decided, and if it loses there is at least a record that it was deferred. The comparison to borrowed money holds: the principal is the cleanup, and while it goes unpaid the interest leaves as extra hours added to every task nearby. The ticket is where that interest gets written down, in a place other people are already looking.

What goes on one of these is fixed. What separates it from a feature ticket is that it describes what is currently generating cost rather than what should be built.

1. State the current condition as fact. Which part is in what shape — the payment code sits in one 3,000-line file with no tests, for instance.
2. Put a number on the cost that condition creates. This field decides whether the ticket survives. Twenty minutes of manual checking before each deploy, three deploys a week, four hours a month gone. Or: every task that touches this file takes an extra half day. Without a number, it cannot compete with a feature, because the feature always arrives with one.
3. State what happens if it stays. If a feature planned for next quarter touches the same file, the fact that its cost will be higher than today's belongs here.
4. Cut the scope down to one cycle. Changing structure while leaving behavior alone is refactoring, and a ticket proposing to refactor the entire payment module never fits into any cycle. Split it: one piece that adds tests first, one that extracts a single function. Each piece has to leave the product working on its own.
5. Rank it in the same place as features. A separately managed list is a list nobody opens. Put it in the prioritization meeting mixed in with feature tickets and compare them side by side.

Many teams add an allocation rule: 15 to 20 percent of a cycle's capacity reserved for this work up front. Without the reservation, urgent features take that room every time, and labelled tickets pile up at the bottom of the list like a graveyard.

The need for one of these usually announces itself in numbers first.

The first case is estimates climbing. When work of a familiar size gets quoted at twice what it was six months ago, it's time to find the cause and write it down. Engineers can usually name the file before anyone asks.

The second is incidents recurring in the same place. An incident is an event that affected the service, and three of them in one module in a single quarter points at that module's structure. Tickets written after the response is over belong in this category, and they tend to carry the clearest evidence of all.

The third is a new feature touching the same area. If the file has to be opened anyway, folding the cleanup into that work is cheaper than doing it separately. Here the ticket gets planned next to the feature ticket rather than against it, which is the easiest version of this argument to win.

The fourth is an external specification changing. When a service you depend on posts a deprecation notice — announcing in advance that something will be removed — you acquire debt with a deadline attached. That kind usually wins its priority argument, because the ceiling on deferring it is not yours to set.

What this ticket is not is equally clear. Something behaving differently from its intent is a bug, and bugs get fixed now. Debt describes structure that works correctly today and gets more expensive over time. Put both under one label and urgent defects get buried among cleanup items.

"I'll file this as a debt ticket rather than a feature. The evidence is deploy time."

Cleanup is being put on the list so it can compete for priority.

"This cycle includes two debt tickets."

Reporting what the reserved share of capacity got spent on, so the reservation stays visible.

"That's a bug, not debt. It can't slide to the next cycle."

A misclassification is about to push urgent work into the queue.

At Pagedeck one of these first won its priority argument once a number was attached. Theo wrote that the document-saving code had no tests, which meant 25 minutes of manual checking before every deploy, and at three deploys a week he put the quarterly figure at sixteen hours.

Mia set that figure next to the development time for a feature. Two features touching document saving were already planned for the quarter, and doing the cleanup first came out to two days off each of their estimates. That put the ticket ahead of both features in the order — not because cleanup matters more, but because the quarter got shorter by doing it first.

The most common mistake is treating it as an internal engineering matter that product has no business in. It's a conversation about code, so it feels outside the room. But what product judges isn't the code — it's the time. Does three days now remove ten days from next quarter's estimates, and are those ten days worth more than the feature being deferred to get them? Leave that judgment to engineering alone and cleanup always loses to whatever is urgent; hand it over entirely and cleanup piles up until whole quarters pass with nothing users can see.

Reading it as a matter of taste — engineers wanting to fix code they dislike — is the other one. Preferences about structure do differ from person to person, so there's room for that reading. But the moment it becomes a ticket, the standard shifts from taste to cost. A ticket that can't fill in field two loses its priority argument, and that is the filter this method provides. "A better structure" and "four hours a month" get treated very differently in the same meeting, and the second phrasing is available far more often than people assume.