Technical Debt Tracking | Identify and Prioritize Debt
Track technical debt with impact-effort prioritization and sprint allocation. GitScrum manages debt items alongside features for healthy codebases.
9 min read
Technical debt slows teams over time. GitScrum helps track debt items and balance them against feature work to maintain codebase health.
Understanding Tech Debt
Types of Debt
TYPES OF TECHNICAL DEBT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DELIBERATE DEBT: │
│ ──────────────── │
│ "We know this is quick and dirty, but we need to ship" │
│ Conscious trade-off, documented │
│ Plan to fix later │
│ │
│ ACCIDENTAL DEBT: │
│ ──────────────── │
│ "We didn't know there was a better way" │
│ Learned better practices after the fact │
│ Outdated patterns │
│ │
│ BIT ROT: │
│ ──────── │
│ "This worked fine until..." │
│ Dependencies outdated │
│ Requirements changed │
│ Environment evolved │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ EXAMPLES: │
│ │
│ CODE: │
│ • Duplicated logic │
│ • Missing tests │
│ • Complex functions (too long) │
│ • Poor naming │
│ • Dead code │
│ │
│ ARCHITECTURE: │
│ • Monolith that should be split │
│ • Wrong data structure │
│ • Tight coupling │
│ • Missing abstraction layer │
│ │
│ INFRASTRUCTURE: │
│ • Manual deployments │
│ • Outdated dependencies │
│ • Missing monitoring │
│ • Insecure configurations │
│ │
│ DOCUMENTATION: │
│ • Outdated docs │
│ • Missing READMEs │
│ • Incorrect comments │
└─────────────────────────────────────────────────────────────┘
Cost of Debt
IMPACT OF TECHNICAL DEBT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ VELOCITY OVER TIME: │
│ │
│ Feature │
│ Velocity │
│ │ │
│ │ ████ │
│ │ ████ ████ │
│ │ ████ ████ ███ │
│ │ ████ ████ ███ ██ │
│ │ ████ ████ ███ ██ █ │
│ └──────────────────────────→ Time │
│ │
│ Without debt management, velocity decreases │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ SYMPTOMS OF HIGH DEBT: │
│ ─────────────────────── │
│ • "Simple changes take forever" │
│ • Frequent bugs in certain areas │
│ • Fear of changing legacy code │
│ • New team members take longer to onboard │
│ • Same bugs keep recurring │
│ • "Nobody knows how this works" │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ THE COMPOUND EFFECT: │
│ ──────────────────── │
│ │
│ Sprint 1: Quick fix (save 2 days) │
│ Sprint 5: Working around it (lose 1 day) │
│ Sprint 10: Bug from the hack (lose 3 days) │
│ Sprint 15: Major refactor needed (lose 1 week) │
│ │
│ Initial 2-day "savings" cost 2+ weeks │
│ │
│ Interest compounds if not addressed. │
└─────────────────────────────────────────────────────────────┘
Tracking Debt
Debt Inventory
TECHNICAL DEBT TRACKING:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DEBT BACKLOG: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ TECH DEBT INVENTORY ││
│ │ ││
│ │ ID ITEM AREA IMPACT EFFORT││
│ │ ───── ──── ──── ────── ──────││
│ │ TD-001 Missing API tests Backend High Medium││
│ │ TD-002 Duplicate user logic Auth Medium Low ││
│ │ TD-003 Outdated React Frontend High High ││
│ │ TD-004 No DB indexes Database High Low ││
│ │ TD-005 Hard-coded config Infra Low Low ││
│ │ TD-006 Monolithic service Arch High High ││
│ │ ││
│ │ PRIORITY MATRIX: ││
│ │ ││
│ │ LOW EFFORT HIGH EFFORT ││
│ │ ┌─────────────┬─────────────┐ ││
│ │ HIGH │ TD-004 │ TD-003 │ ││
│ │ IMPACT │ TD-001 │ TD-006 │ ││
│ │ │ (DO FIRST) │ (PLAN FOR) │ ││
│ │ ├─────────────┼─────────────┤ ││
│ │ LOW │ TD-005 │ (AVOID │ ││
│ │ IMPACT │ TD-002 │ THESE) │ ││
│ │ │ (OPPORTUN.) │ │ ││
│ │ └─────────────┴─────────────┘ ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ WHEN TO LOG DEBT: │
│ ───────────────── │
│ • During code review ("this should be refactored") │
│ • After incidents (root cause is tech debt) │
│ • During estimation ("this is slow because...") │
│ • Proactively during codebase review │
└─────────────────────────────────────────────────────────────┘
Debt Item Template
TECH DEBT TASK:
┌─────────────────────────────────────────────────────────────┐
│ │
│ TD-001: Add API Integration Tests │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ TYPE: Missing tests ││
│ │ AREA: Backend API ││
│ │ DISCOVERED: Sprint 12, during incident ││
│ │ ││
│ │ DESCRIPTION: ││
│ │ Payment API has no integration tests. Changes are ││
│ │ high risk. Last 3 production bugs were in this area. ││
│ │ ││
│ │ IMPACT: ││
│ │ • High - bugs escape to production ││
│ │ • Changes require extensive manual testing ││
│ │ • Fear of refactoring slows development ││
│ │ ││
│ │ COST OF INACTION: ││
│ │ ~2 hours manual testing per change ││
│ │ ~1 production bug per month in this area ││
│ │ ││
│ │ FIX APPROACH: ││
│ │ 1. Add happy path tests for payment flow ││
│ │ 2. Add error case tests ││
│ │ 3. Add to CI pipeline ││
│ │ ││
│ │ ESTIMATE: 5 points ││
│ │ PRIORITY: High (fix this quarter) ││
│ │ ││
│ │ RELATED: ││
│ │ • Incident INC-089 ││
│ │ • STORY-567 (blocked by this) ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Paying Down Debt
Allocation Strategies
TECHNICAL DEBT ALLOCATION:
┌─────────────────────────────────────────────────────────────┐
│ │
│ STRATEGY 1: PERCENTAGE PER SPRINT │
│ ───────────────────────────────── │
│ Reserve 10-20% of capacity for tech debt │
│ │
│ SPRINT CAPACITY: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ │████████████████████│████│ ││
│ │ │ Features │ TD │ ││
│ │ │ 80% │20% │ ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ STRATEGY 2: FIX AS YOU GO │
│ ───────────────────────── │
│ When touching code, leave it better │
│ "Boy Scout Rule" - always improve │
│ Small incremental fixes │
│ │
│ STRATEGY 3: DEDICATED SPRINTS │
│ ───────────────────────────── │
│ Quarterly "hardening sprint" │
│ Focus entirely on tech debt │
│ Good for major refactoring │
│ │
│ STRATEGY 4: TECH DEBT FRIDAYS │
│ ───────────────────────────── │
│ Every Friday afternoon for debt │
│ Regular, predictable time │
│ Developer choice of items │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ WHICH TO USE: │
│ ───────────── │
│ • Light debt: Fix as you go │
│ • Moderate debt: 15% per sprint │
│ • Heavy debt: Dedicated sprint + ongoing % │
│ • Acute crisis: Stop features, fix debt │
└─────────────────────────────────────────────────────────────┘
Making Progress
EFFECTIVE DEBT REDUCTION:
┌─────────────────────────────────────────────────────────────┐
│ │
│ PRIORITIZE BY: │
│ ───────────── │
│ │
│ 1. ACTIVE DEVELOPMENT AREA: │
│ If you're about to work in this code, │
│ fix debt first. Pays off immediately. │
│ │
│ 2. INCIDENT-CAUSING: │
│ Debt that caused production issues │
│ Clear ROI, prevents future incidents │
│ │
│ 3. VELOCITY-BLOCKING: │
│ "We can't add features until we fix this" │
│ Unblocks future work │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ QUARTERLY DEBT REVIEW: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Q4 TECH DEBT REVIEW ││
│ │ ││
│ │ START OF QUARTER: 42 debt items ││
│ │ RESOLVED: 12 items ││
│ │ NEW ITEMS ADDED: 8 items ││
│ │ END OF QUARTER: 38 items ││
│ │ ││
│ │ TREND: ↘ Decreasing (good!) ││
│ │ ││
│ │ HIGHLIGHTS: ││
│ │ ✅ API tests added (TD-001) - 60% fewer bugs ││
│ │ ✅ DB indexes (TD-004) - queries 5x faster ││
│ │ ✅ Config externalized (TD-005) ││
│ │ ││
│ │ NEXT QUARTER FOCUS: ││
│ │ • React upgrade (TD-003) ││
│ │ • Service split phase 1 (TD-006) ││
│ │ ││
│ │ HEALTH: Improving from Red → Yellow ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Preventing New Debt
Debt Prevention
AVOIDING NEW TECHNICAL DEBT:
┌─────────────────────────────────────────────────────────────┐
│ │
│ CODE REVIEW GATES: │
│ ────────────────── │
│ ☐ Tests for new code │
│ ☐ No copied/duplicated code │
│ ☐ Follows existing patterns │
│ ☐ No TODO without ticket │
│ │
│ DEFINITION OF DONE: │
│ ─────────────────── │
│ ☐ Tests written and passing │
│ ☐ Documentation updated │
│ ☐ No new linter warnings │
│ ☐ Peer reviewed │
│ │
│ TECH DEBT DISCUSSION: │
│ ───────────────────── │
│ When taking shortcuts: │
│ 1. Team agrees it's necessary │
│ 2. Document WHY │
│ 3. Create debt ticket immediately │
│ 4. Set expected payback date │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ DELIBERATE DEBT DECISION: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ SHORTCUT APPROVAL ││
│ │ ││
│ │ STORY: STORY-890 ││
│ │ ││
│ │ SHORTCUT: ││
│ │ Skip unit tests to make launch deadline ││
│ │ ││
│ │ JUSTIFICATION: ││
│ │ Critical launch date, will add tests next sprint ││
│ │ ││
│ │ DEBT TICKET CREATED: TD-015 ││
│ │ PLANNED PAYBACK: Sprint 16 ││
│ │ ││
│ │ APPROVED BY: @tech-lead ││
│ │ DATE: Jan 15, 2025 ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ Making debt deliberate and visible │
│ prevents hidden accumulation. │
└─────────────────────────────────────────────────────────────┘