Technical Debt Tracker Ledger | Quantify and Pay Down
Track technical debt like finances: principal, interest, and balance. GitScrum tracks debt items with severity labels, effort points, and sprint allocation.
7 min read
Technical debt accumulates silently until it cripples delivery. Treating debt like a financial ledger—tracking what you owe, interest rates, and payments—provides visibility that enables strategic decisions. GitScrum helps teams maintain a technical debt ledger that makes debt visible and manageable.
Debt Ledger Concept
| Term | Meaning | Example |
|---|---|---|
| Principal | Effort to fix | 8 story points |
| Interest | Ongoing cost | 2 pts/sprint slowdown |
| Balance | Total debt | 81 points |
| Payment | Work done | 6 pts this sprint |
The Technical Debt Ledger
DEBT LEDGER STRUCTURE
═════════════════════
LEDGER ENTRY TEMPLATE:
─────────────────────────────────────
┌─────────────────────────────────────────────────────────────┐
│ DEBT ITEM: [Name] │
│ ID: DEBT-001 │
├─────────────────────────────────────────────────────────────┤
│ │
│ CLASSIFICATION: │
│ ├── Category: Architecture / Code / Test / Docs │
│ ├── Severity: Critical / High / Medium / Low │
│ ├── Age: 6 months │
│ └── Owner: Backend Team │
│ │
│ FINANCIALS: │
│ ├── Principal: 13 points (effort to fix) │
│ ├── Interest Rate: 3 pts/sprint (ongoing cost) │
│ ├── Total Interest Paid: 18 pts (3 × 6 sprints) │
│ └── Break-even: 4.3 sprints │
│ │
│ IMPACT: │
│ ├── Affects: User service, Order service │
│ ├── Symptoms: Slow builds, frequent bugs │
│ └── Risk: Increases with each change │
│ │
│ STATUS: │
│ ├── Current: Accruing interest │
│ ├── Planned: Sprint 25 │
│ └── Payments: None yet │
│ │
└─────────────────────────────────────────────────────────────┘
GitScrum Debt Tracking Setup
SETTING UP DEBT TRACKING
════════════════════════
STEP 1: CREATE LABELS
─────────────────────────────────────
Labels for categorization:
├── [debt:architecture]
├── [debt:code-quality]
├── [debt:testing]
├── [debt:documentation]
├── [debt:infrastructure]
└── [debt:security]
Severity labels:
├── [severity:critical]
├── [severity:high]
├── [severity:medium]
└── [severity:low]
STEP 2: CREATE DEBT EPIC
─────────────────────────────────────
Epic: Technical Debt Ledger Q1 2025
Description:
├── Total Balance: 81 points
├── Sprint Allocation: 8 pts/sprint
├── Target Reduction: 40%
└── Review: Monthly
STEP 3: ADD DEBT ITEMS AS TASKS
─────────────────────────────────────
Each debt item becomes a task:
├── Title: [DEBT] Description
├── Labels: Category + Severity
├── Effort: Principal points
├── Description: Ledger details
└── Parent: Debt Epic
Debt Inventory Dashboard
TECHNICAL DEBT LEDGER - Q1 2025
═══════════════════════════════
SUMMARY:
─────────────────────────────────────
Total Balance: 81 points
Sprint Interest: 12 pts/sprint
Monthly Interest: 24 pts/month
BREAKDOWN BY CATEGORY:
─────────────────────────────────────
Architecture ████████████████░░ 32 pts (40%)
Code Quality ████████████░░░░░░ 24 pts (30%)
Testing ██████░░░░░░░░░░░░ 12 pts (15%)
Documentation ████░░░░░░░░░░░░░░ 8 pts (10%)
Infrastructure ██░░░░░░░░░░░░░░░░ 5 pts ( 5%)
BREAKDOWN BY SEVERITY:
─────────────────────────────────────
Critical ████░░░░░░░░░░░░░░ 8 pts (10%)
High ████████████░░░░░░ 24 pts (30%)
Medium ████████████████░░ 32 pts (40%)
Low ██████░░░░░░░░░░░░ 17 pts (21%)
TOP 5 HIGHEST INTEREST ITEMS:
─────────────────────────────────────
┌───────────────────────────────────────────────────────────┐
│ # │ Item │ Principal │ Interest/Spr │
├───┼───────────────────────────┼───────────┼──────────────┤
│ 1 │ Legacy auth system │ 21 pts │ 4 pts │
│ 2 │ Monolithic service │ 34 pts │ 3 pts │
│ 3 │ Missing integration tests │ 13 pts │ 2 pts │
│ 4 │ Outdated dependencies │ 8 pts │ 2 pts │
│ 5 │ Hard-coded config │ 5 pts │ 1 pt │
└───┴───────────────────────────┴───────────┴──────────────┘
Interest Calculation
CALCULATING DEBT INTEREST
═════════════════════════
WHAT COUNTS AS INTEREST:
─────────────────────────────────────
Interest = ongoing cost of NOT fixing
Measurable costs:
├── Extra time on related features
├── Bug fixes caused by debt
├── Workaround maintenance
├── Cognitive load
├── Onboarding friction
└── Testing overhead
CALCULATION EXAMPLE:
─────────────────────────────────────
Debt: Hard-coded database connections
Principal (effort to fix):
├── Refactor code: 3 pts
├── Add config management: 2 pts
├── Update environments: 1 pt
└── Total Principal: 6 pts
Interest (per sprint):
├── Manual env changes: 0.5 hrs
├── Related bugs: 0.5 pts avg
├── Deployment friction: 0.25 pts
└── Total Interest: ~1 pt/sprint
Break-even: 6 sprints
Recommendation: Fix now
ROI CALCULATION:
─────────────────────────────────────
If Principal = 6 pts
And Interest = 1 pt/sprint
Then:
├── After 6 sprints: Break even
├── After 12 sprints: 6 pts saved
├── After 24 sprints: 18 pts saved
└── Decision: Fix if runway > 6 sprints
Payment Strategies
DEBT PAYMENT APPROACHES
═══════════════════════
STRATEGY 1: HIGHEST INTEREST FIRST
─────────────────────────────────────
Pay down debt with highest interest rate
Like credit card payoff:
├── Maximum velocity recovery
├── Quick wins on efficiency
├── Visible improvement fast
└── Recommended for most teams
STRATEGY 2: LOWEST PRINCIPAL FIRST
─────────────────────────────────────
Quick wins, clear items off ledger
Benefits:
├── Momentum building
├── Team motivation
├── Reduced complexity
└── Good for morale
STRATEGY 3: OPPORTUNITY-BASED
─────────────────────────────────────
Pay when working in affected area
"Boy Scout Rule":
├── Leave code better than found
├── Low overhead
├── Natural integration
└── Sustainable pace
RECOMMENDED: HYBRID APPROACH
─────────────────────────────────────
├── 20% capacity for dedicated debt
│ └── High interest items
├── Opportunity-based for rest
│ └── While working nearby
└── Review quarterly
└── Adjust strategy
Sprint Allocation
SPRINT PLANNING WITH DEBT
═════════════════════════
CAPACITY ALLOCATION:
─────────────────────────────────────
Team Velocity: 40 pts/sprint
┌─────────────────────────────────────┐
│ Feature Work │ 28 pts (70%) │
│ Technical Debt │ 8 pts (20%) │
│ Bugs & Maintenance │ 4 pts (10%) │
└─────────────────────┴──────────────┘
SPRINT DEBT SELECTION:
─────────────────────────────────────
Priority order:
1. Debt blocking planned features
2. Highest interest rate items
3. Debt in areas being modified
4. Quick wins (low principal)
5. Age-based rotation
TRACKING PAYMENTS:
─────────────────────────────────────
Sprint 24 Debt Work:
├── DEBT-003: Config refactor (5 pts) ✓
├── DEBT-007: Test coverage (3 pts) ✓
├── Total Paid: 8 pts
├── New Debt Added: 2 pts
└── Net Reduction: 6 pts
Ledger Update:
├── Previous Balance: 81 pts
├── Payments: -8 pts
├── New Debt: +2 pts
└── New Balance: 75 pts
Monthly Review
DEBT LEDGER REVIEW
══════════════════
MONTHLY REVIEW AGENDA:
─────────────────────────────────────
1. Balance Report
├── Current total
├── Change from last month
└── Trend analysis
2. Interest Analysis
├── Highest interest items
├── Interest paid this month
└── Velocity impact
3. Payment Progress
├── Debt paid down
├── New debt added
└── Net change
4. Priority Adjustment
├── Reprioritize items
├── Update estimates
└── Adjust strategy
5. Next Month Plan
├── Targeted items
├── Capacity allocation
└── Goals
METRICS TO TRACK:
─────────────────────────────────────
├── Total debt balance (points)
├── Debt ratio (debt / velocity)
├── Interest rate (pts/sprint)
├── Payment rate (pts/sprint)
├── Net change trend
└── Time to debt-free (projected)
Best Practices
Anti-Patterns
✗ No tracking (invisible debt)
✗ No allocation (never paid)
✗ Only fixing when crisis
✗ Adding faster than paying
✗ No interest calculation
✗ Quarterly "debt sprints" only