Track Technical Debt | Labels, Priorities, Sprints

Stop losing track of technical debt. GitScrum labels, prioritization matrix, and 20% sprint allocation prevent codebase degradation and velocity decline.

8 min read

Technical debt accumulates silently until it cripples development velocity. GitScrum provides structured tracking with labels, prioritization, and sprint allocation to manage debt systematically before it becomes an emergency.

The Technical Debt Problem

Untracked debt creates compounding issues:

Invisible accumulation — No visibility into debt growth
Deferred indefinitely — Always deprioritized for features
Sudden crises — Small issues become major outages
Velocity decline — Everything takes longer over time
Developer frustration — Working in degraded codebases
Estimation errors — Debt makes new work unpredictable

GitScrum Debt Tracking Solution

Systematic debt management in GitScrum:

Key Features

Feature	Debt Management Use
Labels	Categorize debt types
Priority levels	Rank by impact/urgency
Sprint allocation	Dedicated debt capacity
Task linking	Connect debt to features
NoteVault	Document debt decisions

Setting Up Debt Tracking

Create Debt Labels

Labels for Technical Debt:
├── tech-debt          (parent category)
├── debt-architecture  (structural issues)
├── debt-performance   (speed/efficiency)
├── debt-security      (security concerns)
├── debt-testing       (test coverage gaps)
├── debt-documentation (missing docs)
└── debt-dependencies  (outdated packages)

Priority Levels

Priority Matrix for Debt:
├── Critical — Blocking features or causing incidents
├── High     — Significantly slowing development
├── Medium   — Noticeable friction, manageable
└── Low      — Cleanup, nice to have

Create Debt Template

Task Template: Technical Debt Item

Title: [DEBT] Brief description
Description:
  - What: Current problematic state
  - Why: How this became debt
  - Impact: Effect on development/product
  - Solution: Proposed fix approach
  - Effort: Estimated time to resolve
  - Risk: Consequences if not addressed

Labels: tech-debt, [debt-type]
Priority: [Critical/High/Medium/Low]

Capturing Technical Debt

When to Log Debt

Log debt when:
├── Implementing workarounds to ship features
├── Skipping tests to meet deadlines
├── Copy-pasting instead of refactoring
├── Ignoring deprecation warnings
├── Hardcoding values that should be config
├── Leaving TODO comments in code
└── Discovering undocumented tribal knowledge

Debt Task Example

[DEBT] Payment module uses deprecated Stripe API

What: Payment processing uses Stripe API v1, deprecated 
since 2023. Current code still works but receives no 
security updates.

Why: Original implementation in 2021, no capacity for 
migration during feature pushes.

Impact: 
- Security risk from unmaintained API
- Missing new payment features
- Will break when v1 sunset (Jan 2025)

Solution: Migrate to Stripe API v3
- Update SDK dependency
- Refactor payment service
- Update webhook handlers
- Test all payment flows

Effort: 3-5 days for senior developer
Risk: High - service will fail after sunset date

Labels: tech-debt, debt-security, debt-dependencies
Priority: Critical
Deadline: Before Jan 2025

Debt Prioritization

Impact/Effort Matrix

                    Low Effort    High Effort
                   ┌─────────────┬─────────────┐
High Impact        │ DO FIRST    │ PLAN FOR    │
                   │ Quick wins  │ Major work  │
                   ├─────────────┼─────────────┤
Low Impact         │ FILL GAPS   │ DEFER       │
                   │ Easy cleanup│ Not worth it│
                   └─────────────┴─────────────┘

Prioritization Criteria

Factor	Questions
Severity	How broken is it?
Frequency	How often does it cause problems?
Spread	How much code is affected?
Risk	What's the worst case?
Effort	How long to fix?
Dependencies	Does other work depend on this?

Sprint Allocation for Debt

The 20% Rule

Reserve capacity for debt work:

Sprint Capacity: 100 points
├── Features: 80 points (80%)
└── Tech Debt: 20 points (20%)

Consistent allocation prevents:
- Debt accumulation
- Sprint-to-sprint variance
- "Debt sprints" that frustrate stakeholders

Debt Sprint Planning

Sprint Planning for Debt:

1. Review debt backlog
2. Check critical/high priority items
3. Match to available capacity (20%)
4. Select items that:
   - Pair well with planned features
   - Address current pain points
   - Have clear completion criteria
5. Assign to developers with context

Linking Debt to Features

Connect Related Work

Feature Task #234: Add subscription billing
├── Linked Debt Tasks:
│   ├── #198: [DEBT] Migrate to Stripe API v3
│   │   └── Reason: Required for subscription features
│   ├── #210: [DEBT] Add payment retry logic
│   │   └── Reason: Subscriptions need auto-retry
│   └── #215: [DEBT] Improve payment error handling
│       └── Reason: Better UX for recurring failures

Benefits of Linking

Justify debt work to stakeholders
Surface hidden prerequisites
Accurate feature estimates
Natural debt resolution during features

Debt Visibility

Board View for Debt

Kanban Board: Technical Debt
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ Backlog (23) │ Planned (5)  │ In Progress  │ Resolved (8) │
├──────────────┼──────────────┼──────────────┼──────────────┤
│ [DEBT] Auth  │ [DEBT] API   │ [DEBT] Stripe│ [DEBT] Tests │
│ [DEBT] Cache │ [DEBT] Logs  │ migration    │ [DEBT] Docs  │
│ [DEBT] Tests │ [DEBT] DB    │              │ ...          │
│ ...          │ ...          │              │              │
└──────────────┴──────────────┴──────────────┴──────────────┘

Dashboard Metrics

Track debt health over time:

Technical Debt Dashboard
━━━━━━━━━━━━━━━━━━━━━━━━

Total Debt Items: 45
├── Critical: 3 🔴
├── High: 12 🟡
├── Medium: 18 🟢
└── Low: 12 ⚪

This Sprint:
├── Planned: 5 items (23 points)
└── Resolved: 3 items (15 points)

Trend: ↓ 4% from last month
Oldest Item: 8 months (DB migration)

Documentation in NoteVault

Technical Debt Registry

NoteVault: Technical Debt Registry

## Overview
This document tracks major technical debt items and 
their business context.

## Active Debt

### Payment System
- **Issue**: Stripe API v1 deprecated
- **Owner**: @backend-team
- **Status**: Planned for Q1
- **Business Impact**: Security risk, missing features
- **Resolution Plan**: #198

### Authentication
- **Issue**: No refresh token rotation
- **Owner**: @security-team
- **Status**: In progress
- **Business Impact**: Security compliance gap
- **Resolution Plan**: #245

## Resolved Debt
| Item | Resolved | Time Spent | Notes |
|------|----------|------------|-------|
| Legacy ORM | Nov 2024 | 2 weeks | Full migration |
| Test coverage | Oct 2024 | 3 sprints | 40% → 80% |

Debt Reviews

Regular Debt Meetings

Monthly Technical Debt Review

Agenda:
1. Review debt metrics (15 min)
   - New debt logged
   - Debt resolved
   - Trend direction

2. Triage new items (20 min)
   - Assign priority
   - Estimate effort
   - Identify quick wins

3. Plan upcoming sprint (15 min)
   - Select debt for next sprint
   - Assign owners
   - Link to features

4. Discuss blockers (10 min)
   - Stuck items
   - Resource needs
   - Stakeholder alignment

Retrospective Integration

Address debt in retros:

Sprint Retrospective

What slowed us down?
├── "Payment retry failures wasted 2 days debugging"
│   └── Action: Prioritize #210 (retry logic debt)
├── "Flaky tests caused false alarms"
│   └── Action: Add #260 (test stability debt)

Preventing New Debt

Definition of Done

Definition of Done (includes debt prevention):
☑ Feature complete per requirements
☑ Unit tests written (>80% coverage)
☑ Integration tests pass
☑ Documentation updated
☑ No new TODO comments without ticket
☑ Dependencies updated if touched
☑ Code review approved
☑ No security warnings
☑ Performance acceptable

Code Review Checklist

Debt-Aware Code Review:

□ Does this introduce new debt?
  - If yes, is ticket created?
□ Does this resolve any existing debt?
  - If yes, link and close debt ticket
□ Are there workarounds?
  - Document why, create cleanup ticket
□ Are dependencies current?
  - Check for deprecations
□ Is test coverage maintained?
  - No coverage regression

Communicating Debt to Stakeholders

Business Language Translation

Technical → Business Impact

"API is deprecated"
→ "Security risk: no patches after January"

"Test coverage is low"  
→ "Release risk: bugs more likely in production"

"Architecture is monolithic"
→ "Delivery speed: features take 3x longer"

"Dependencies are outdated"
→ "Compliance risk: known vulnerabilities"

Debt Burn-down Report

Q4 Technical Debt Report

Started Q4: 52 debt items (312 points)
Resolved: 18 items (98 points)
Added: 7 items (43 points)
End Q4: 41 items (257 points)

Net Reduction: 11 items (55 points) ↓17%

Highlights:
✓ Completed Stripe migration (critical)
✓ Test coverage improved 15%
⚠ Database migration still pending