Debt categorized and prioritized

Debt categorized and prioritized is the L2 state where an organization has moved from informal awareness of technical debt to a structured system for tracking, classifying, and ordering debt items. Instead of a vague shared understanding that "the authentication module is a mess," the team has a documented debt inventory where each item has a category, a severity, and a priority ranking that determines what gets addressed and when.

The categorization step is the foundation. Debt falls into several distinct types, and each type has different remediation strategies and different business urgencies. Security debt - outdated dependencies with known CVEs, deprecated authentication patterns, unencrypted data at rest - is the most urgent because it has direct risk implications. Architectural debt - inappropriate coupling, violated domain boundaries, patterns that no longer match the current system's needs - is the most expensive because it makes every feature in the affected area more costly. Test debt - missing coverage, unreliable tests, tests that verify implementation rather than behavior - directly impacts deployment confidence. Documentation debt limits knowledge transfer and onboarding. Identifying which type of debt each item represents determines who addresses it and how.

The prioritization step translates the inventory into a work queue. Prioritization criteria typically include urgency (does this debt have a deadline, such as an end-of-life dependency?), impact (how many developers does this slow down, how frequently?), remediation cost (how much work is required to address it?), and risk (what is the worst-case consequence if this debt is not addressed?). A simple scoring matrix across these dimensions produces a prioritized list that is more defensible and more useful than pure gut feel.

At L2, the debt inventory is a living document rather than a one-time audit. New debt is added as it is created or discovered. Items are removed when addressed. Priority scores are reviewed quarterly. The inventory becomes the basis for planning: debt reduction work is selected from the top of the priority list rather than chosen ad hoc.

• Converts invisible costs to visible decisions - A categorized and prioritized debt inventory makes the cost of deferral explicit; when a security debt item sits at the top of the list for two quarters, that is a documented decision with documented risk, not an oversight
• Enables systematic remediation - Items in the same category can be addressed together using the same tools and patterns; categorization enables batch remediation rather than one-off fixes
• Creates a shared language for debt conversations - When debt has names, categories, and scores, conversations about tradeoffs become more precise; "this is P1 security debt" is a more actionable statement than "this code is a mess"
• Sets up AI automation - A well-maintained debt inventory at L2 is the input queue for AI-assisted remediation at L3; agents need a structured list of items to work from
• Demonstrates organizational maturity to stakeholders - A debt registry with clear prioritization signals to executives and auditors that engineering is managing risk deliberately, not reactively

1. Establish debt categories - Define the categories your team will use: Security, Architectural, Test, Documentation, Dependency (version currency). Definitions should be crisp enough that any developer can classify a new item without ambiguity.
2. Run an initial inventory sprint - Spend one sprint with the whole team contributing to the debt inventory. Use the category definitions. Aim for 20-40 items that represent the most significant known debt, not an exhaustive list of every code smell.
3. Create a scoring rubric - Define scoring for urgency (1-3), impact (1-3), and remediation cost (inverse: expensive = lower score). Calculate a priority score: urgency x impact / cost. The formula can be adjusted, but a formula is better than pure ranking.
4. Select the top 5 items for the next quarter - Pick the five highest-priority items and add them to the sprint backlog for the next quarter. These are not optional "if there's time" items - they are committed work.
5. Add debt tracking to your definition of done - When a developer creates technical debt to meet a deadline, they create a debt inventory item at the same time. This stops the inventory from becoming stale and makes debt creation a deliberate, documented decision.
6. Review and re-score quarterly - Priority changes as the business changes. An item that was low urgency becomes urgent when its dependency reaches end-of-life. Schedule a quarterly debt review meeting to update scores and re-sequence the queue.

Building the inventory once and never updating it. A static debt registry becomes incorrect within weeks as code changes, new debt is created, and old items are addressed. The inventory is only useful if it is maintained as a living document with clear ownership.

Scoring every item the same. If most items end up with similar priority scores, the scoring rubric is not discriminating enough. Good prioritization should produce a clear top 10% that the team agrees should be addressed next. If everything is high priority, nothing is.

Separating debt work from feature work. Teams that maintain debt backlogs but plan them in a separate process from feature work find that debt items never get done because they are never competing in the same sprint planning session. Debt items should be in the same backlog as features, selected by the same prioritization process.

Missing the security category. Many organizations build debt inventories focused on architectural or test debt and undercount security debt. Outdated dependencies with known CVEs are tech debt with an immediate risk profile. They should be tracked, scored, and addressed on the same cadence as other debt.

No single owner for the inventory. A debt inventory with no named owner becomes everyone's responsibility and no one's priority. Assign a single owner - typically the lead engineer or tech lead - who is accountable for the inventory being current and for debt items being addressed.

How this guide changed across editions, newest first.

August 2026 (v1.5)

Added comprehension debt (Addy Osmani) to the inventory: code that nobody on the team understands, accumulated wherever machines verify machines. It pairs with the Agentic Technical Debt / Stochastic Tax vocabulary and with ACM Queue's cycle of intent debt feeding cognitive debt feeding technical debt. Track it like the others, by flagging areas where no current team member can explain why the code is shaped the way it is. July also delivered a counter-datapoint on the remediation side: Bun was rewritten from Zig to Rust in 11 days for about $165K, 535,496 lines, with the TypeScript suite acting as a conformance harness, and sqlite-utils 4.0 was written agentically for roughly $149. Modernization is cheap now, but only where a conformance oracle exists. Two rules entered the prioritization rubric: check whether the oracle exists before scoring an agent-scale rewrite as feasible, and check what durable side effects "disposable" code left behind before deleting it.

July 2026 (v1.4)

Added intent as a categorization lens. a16z's Disposable Software and Fowler's Sacrificial Architecture argue that some artifacts are built to be thrown away, so debt scoring should separate them from durable systems. The warning to encode in the inventory: disposable code, durable side effects. The data written, integrations opened and security surface exposed all outlive the code that created them.

June 2026 (v1.3)

Sharpened the vocabulary again with arXiv 2605.29129 (May 27): Agentic Technical Debt is a stock of liability from un-governed prompts, tool schemas and orchestration, while the Stochastic Tax is the recurring flow-cost of keeping probabilistic agents in bounds. The DORA ROI report added that AI gains collapse to roughly 10% on complex legacy code.

May 2026 (v1.2)

Added two debt categories to the L2 inventory, separate from classic legacy and maintenance debt.

• Context debt. When agent iteration runs faster than architectural integrity, the codebase accumulates inconsistent patterns, shallow abstractions and duplication. Senior leaders reported a roughly 12-week unmaintainability cliff for vibe-coded repos with no steering. Track it by area: distinct patterns for the same concern, drift between CLAUDE.md/AGENTS.md rules and actual code, dead spec files.
• Verification debt. April reporting put the velocity gain from Claude Code and Gemini-CLI at roughly 3x per ticket, but verification overhead at +125%. The gap is the debt. Track unreviewed-merged ratio, post-merge bug rate trend, and time-to-verification per ticket.

Both compound the same way as classic debt. The difference is that they are produced by your tools, not avoided by them.