Section 40 · Team & Development
Technical Debt Tracking
Audit technical debt visibility, management practices, and metrics
This guide walks you through auditing a project's technical debt visibility, management, and metrics.
The Goal: Visible, Managed Debt
Technical debt is inevitable. The question is whether it's:
- Visible — explicitly tracked, not just "known"
- Structured — prioritized with enough context to act on
- Managed — regularly reviewed, allocated time, actually reduced
Invisible debt compounds silently. This guide verifies the practices that keep debt under control.
Cross-references:
- Section 8 (Testing & Code Metrics) covers CRAP score
- Section 2 (Dependencies & Code Quality) covers dependency updates
- Section 28 (Code Architecture) covers SOLID principles and quality tools
Before You Start
- Identify where debt is tracked (Linear, Jira, GitHub Issues, Notion, dedicated doc)
- Understand the team's sprint/planning cadence (affects review frequency expectations)
- Check team size (smaller teams may have informal but effective processes)
visibility
Technical debt is explicitly tracked in a dedicated location (board, label, document), actively maintained, and discoverable by team members.
“Name your top three debt items right now.”
Debt items have structured fields including description, impact, estimated effort, and priority to enable informed prioritization.
“Pick a debt item — does it say why it matters?”
management
Debt list is reviewed on a regular cadence (quarterly minimum) to prioritize items, close stale entries, and prevent debt from compounding indefinitely.
“When was your last debt review — and what changed?”
Protected time is allocated for debt reduction (e.g., 10-20% of sprints), and debt work actually gets done.
“What percentage of last sprint went to debt? Really?”
Debt resolution is tracked over time to validate allocation is working and provide visibility into whether debt is growing or shrinking.
“Is your debt list shrinking or just growing?”
metrics
Code complexity is measured and tracked over time to catch debt accumulation early.
“Which file is your most complex — and is it getting worse?”
Dependency updates are automated, security vulnerabilities are tracked, and major dependencies are kept reasonably current.
“Any dependencies more than two major versions behind?”
TODO and FIXME comments are tracked as informal debt markers, with visibility into count and age.
“How many TODOs are older than your newest engineer?”