A new analytics leader asked me last week how I decide what technical debt to pay down inside a function. The honest answer is that I categorise debt into four bands, and I treat each band differently. I have not seen anybody else write about this in quite this language, so it is worth setting down.
Band one: structural debt
Structural debt is the debt that compounds. It is in the choice of data warehouse, the way identity is resolved across systems, the shape of the canonical customer model, and the schema of the metrics layer. When this kind of debt is wrong, every downstream piece of work pays interest. A bad customer identity model means that every dashboard, every cohort analysis, and every machine learning feature is fighting the same problem in slightly different ways.
Structural debt has to be paid down. It has to be paid down even when the business is screaming for the next deliverable, because the cost of leaving it is non-linear. The way I budget for it is to put one engineer on a permanent rotation that does nothing else for six to twelve months. That is expensive. It is cheaper than the alternative.
Band two: hygiene debt
Hygiene debt is real but not strategic. It is the dashboards that nobody owns, the dbt models that have not been touched in eighteen months, the manual reconciliations that should be automated. This kind of debt costs the team time every week, but the cost is roughly linear and predictable.
I treat hygiene debt as a fixed budget item. Twenty per cent of sprint capacity, every sprint. Not negotiated, not deferred, not borrowed against. The reason it is fixed is that hygiene debt expands to fill the available neglect. A team that does not pay this every sprint is a team that will have a debt crisis in twelve months.
Band three: documentation debt
Documentation debt is the debt that hurts most when the wrong person leaves. The senior analyst who knew why the revenue model treats refunds the way it does. The data engineer who designed the change-data-capture layer. The product analyst who set up the experiment design framework.
I have learned to treat this debt as a hiring concern. The question I ask of any senior on the team is not whether they have written down what they know. It is whether the team could ship without them for a month. If the answer is no, the documentation debt is structural and it has just become a retention problem in disguise.
Band four: cosmetic debt
Cosmetic debt is the debt that engineers want to fix but the business does not feel. It is the rename of the inconsistent table, the reformat of the dbt project structure, the migration to the slightly newer version of the orchestration framework.
I do not pay this debt down on its own time. I pay it down only when it sits next to something that needs to change anyway. That is unpopular with engineers. It is the right call. A team that paid down cosmetic debt on its own merits would never ship anything that the business cared about, and would feel incrementally cleaner about a codebase that produced no value.
The leadership move
The reason this categorisation matters is that most analytics leaders treat debt as a single bucket and prioritise it by recency or by which engineer complained most recently. That is how you end up with a team that has a beautiful dbt project structure and an unowned customer identity model.
The categorisation forces a different question. Which kind of debt is this, and what is the right cadence for paying it. Structural debt gets a dedicated person. Hygiene debt gets a fixed sprint allocation. Documentation debt gets treated as a retention risk. Cosmetic debt gets paid only opportunistically. None of those answers are difficult. The leadership challenge is saying them out loud and refusing to deviate.
Once you have the framework, the team's relationship with debt changes. Engineers stop feeling that their requests for cleanup are being ignored, because they understand the categorisation. Business stakeholders stop feeling that the team is endlessly refactoring, because the cadence is predictable. And you, as the leader, stop spending your decision energy on the same debt argument every quarter. That is the trade you are making when you commit to a framework. It is worth making.