Technical Debt Documentation | Track and Prioritize
Document technical debt with impact, cost, and risk assessments. GitScrum tracks debt items in backlogs with labels, severity levels, and custom fields.
7 min read
Technical debt accumulates silently, slowing development until teams can't ignore it. Documentation makes debt visible, quantifiable, and actionable. Well-documented debt enables informed trade-offs between paying it down and shipping features.
Documentation Elements
| Element | Purpose | Example |
|---|---|---|
| Description | What is the debt | Legacy auth system |
| Location | Where it lives | /src/auth/*.js |
| Impact | How it hurts | +2h per feature |
| Cost | Effort to fix | 3 sprints |
| Risk | What could happen | Security breach |
Debt Documentation Format
Standard Template
TECHNICAL DEBT ITEM TEMPLATE
════════════════════════════
TITLE:
─────────────────────────────────────
Clear, concise name
"Legacy authentication system"
"Monolithic test suite"
"Inconsistent API responses"
DESCRIPTION:
─────────────────────────────────────
What is the debt?
Why does it exist?
When was it introduced?
Example:
"Authentication was built quickly for MVP.
Uses outdated bcrypt version, no OAuth,
session management is custom-built.
Introduced: 2021 Q2, 3 developers ago."
LOCATION:
─────────────────────────────────────
Which files/services/modules?
├── /src/auth/
├── /src/middleware/session.js
├── /src/controllers/login.js
├── Related: /tests/auth/*.test.js
└── Lines affected: ~2000
IMPACT:
─────────────────────────────────────
How does it slow us down?
├── New auth features take +2 days
├── Onboarding: 1 week to understand
├── Security reviews flag it every time
├── CI runs 15 min longer
└── Quantify where possible
COST TO FIX:
─────────────────────────────────────
What would remediation take?
├── Estimated effort: 3 sprints
├── Team members: 2 developers
├── External: Security review $5K
├── Risk during migration: Medium
└── Downtime: 2 hours planned
RISK IF IGNORED:
─────────────────────────────────────
What could go wrong?
├── Security: Vulnerability exploitation
├── Scalability: Won't handle growth
├── Team: Key developer leaves
├── Business: Customer data breach
└── Severity: High / Medium / Low
PRIORITY RECOMMENDATION:
─────────────────────────────────────
├── Urgency: Address in next 2 quarters
├── Compare to other debt items
├── Consider strategic timing
└── Next steps: Include in Q3 planning
Categorizing Debt
Debt Types
TECHNICAL DEBT CATEGORIES
═════════════════════════
CODE QUALITY:
─────────────────────────────────────
├── Duplicate code
├── Complex functions
├── Poor naming
├── Missing abstractions
├── Inconsistent patterns
└── Fix: Refactoring sprints
ARCHITECTURE:
─────────────────────────────────────
├── Monolith needing decomposition
├── Wrong technology choice
├── Missing service boundaries
├── Scaling limitations
├── Tight coupling
└── Fix: Major initiatives
TESTING:
─────────────────────────────────────
├── Missing tests
├── Slow test suite
├── Flaky tests
├── No integration tests
├── Unmaintained tests
└── Fix: Test improvement sprints
INFRASTRUCTURE:
─────────────────────────────────────
├── Outdated dependencies
├── Manual deployment
├── No monitoring
├── Scaling limitations
├── Configuration drift
└── Fix: Infrastructure initiatives
DOCUMENTATION:
─────────────────────────────────────
├── Missing docs
├── Outdated docs
├── No onboarding guides
├── Tribal knowledge
├── No architecture docs
└── Fix: Documentation sprints
TRACKING BY CATEGORY:
─────────────────────────────────────
Label debt items by category.
Enables analysis:
"60% of our debt is testing-related.
Focus test improvement."
Severity Levels
DEBT SEVERITY LEVELS
════════════════════
CRITICAL:
─────────────────────────────────────
├── Active security vulnerability
├── Regular production incidents
├── Blocking business operations
├── Must address immediately
└── Treat as production issue
HIGH:
─────────────────────────────────────
├── Significant development slowdown
├── Frequent bugs in this area
├── Customer-facing quality issues
├── Address within 1-2 quarters
└── Major backlog item
MEDIUM:
─────────────────────────────────────
├── Noticeable friction
├── Occasional issues
├── Onboarding impact
├── Address within 2-4 quarters
└── Regular backlog item
LOW:
─────────────────────────────────────
├── Minor annoyance
├── Best practice gap
├── Nice to improve
├── Address opportunistically
└── When touching that code anyway
Tracking in GitScrum
Debt Backlog
GITSCRUM DEBT TRACKING
══════════════════════
CREATE DEBT BACKLOG:
─────────────────────────────────────
Option 1: Label in main backlog
├── Label: "tech-debt"
├── Filter to view all debt
├── Competes with features
└── Single prioritization
Option 2: Separate debt board
├── Dedicated Tech Debt board
├── Own workflow
├── Link to feature work
└── Separate visibility
RECOMMENDED APPROACH:
─────────────────────────────────────
Main backlog with label:
├── Debt visible alongside features
├── Forces trade-off conversations
├── Doesn't get forgotten
├── PO sees full picture
└── Team capacity includes debt
TASK STRUCTURE:
─────────────────────────────────────
Title: [DEBT] Legacy authentication system
Description: (Use template from above)
Labels: tech-debt, security, high-priority
Story Points: 21 (large effort)
Links: Related feature work
Attachments: Architecture diagrams
CUSTOM FIELDS:
─────────────────────────────────────
├── Debt Category (dropdown)
├── Severity (Critical/High/Med/Low)
├── Estimated Cost (story points)
├── Impact Score (1-10)
├── Date Discovered
└── Enable tracking and reporting
Maintaining Documentation
Keeping Current
DEBT DOCUMENTATION MAINTENANCE
══════════════════════════════
WHEN TO DOCUMENT:
─────────────────────────────────────
├── Sprint retrospective: "What slowed us?"
├── Code review: "This should be fixed"
├── Bug investigation: "Root cause is debt"
├── Onboarding: New person notices issues
├── Architecture review: Problems surface
└── Capture when discovered
REGULAR REVIEW:
─────────────────────────────────────
Quarterly Tech Debt Review:
├── Review all documented debt
├── Still relevant? Update or close
├── Severity changed? Adjust
├── Partially addressed? Update status
├── New debt discovered? Add it
└── Keep documentation fresh
GROOMING DEBT:
─────────────────────────────────────
Include debt in backlog grooming:
├── Review high-priority debt
├── Refine effort estimates
├── Identify opportunities
├── Bundle with related features
└── Keep ready for sprint
CLOSING DEBT:
─────────────────────────────────────
When debt is addressed:
├── Document what was done
├── Note actual effort (vs estimate)
├── Link to PRs/commits
├── Lessons learned
├── Close the item
└── Celebrate!
DEBT METRICS:
─────────────────────────────────────
Track over time:
├── Total debt items
├── New debt added per quarter
├── Debt addressed per quarter
├── Debt by category
├── Age of oldest debt
└── Trend: Getting better or worse?
Communicating Debt
Stakeholder Communication
COMMUNICATING DEBT TO STAKEHOLDERS
══════════════════════════════════
MAKE IT VISIBLE:
─────────────────────────────────────
Dashboard widget:
┌─────────────────────────────────────┐
│ Technical Debt Summary │
├─────────────────────────────────────┤
│ Total Items: 47 │
│ Critical: 2 High: 8 Med: 37 │
│ Est. Effort: 89 story points │
│ Added this Q: 12 │
│ Addressed this Q: 7 │
│ Trend: ⚠️ Growing │
└─────────────────────────────────────┘
SPEAK BUSINESS LANGUAGE:
─────────────────────────────────────
Instead of: "Auth system needs refactoring"
Say: "Our login system is 3 years old.
Each new feature takes 2 extra days.
Security review flagged 4 concerns.
$30K to fix now, vs unknown cost later."
QUANTIFY IMPACT:
─────────────────────────────────────
├── "Losing 10 dev hours per sprint"
├── "3 bugs per month from this code"
├── "Onboarding takes 2 weeks longer"
├── "Can't add feature X without this"
└── Numbers make it real
PROPOSE TRADE-OFFS:
─────────────────────────────────────
"We can either:
A) Ship 2 features this quarter + no debt work
B) Ship 1 feature + address critical debt
Option B reduces ongoing friction
and enables faster Q4."
Let stakeholders make informed choices.
Best Practices
For Debt Documentation
Anti-Patterns
DEBT DOCUMENTATION MISTAKES:
✗ Undocumented debt
✗ Vague descriptions
✗ No effort estimate
✗ Never updating status
✗ Hidden from stakeholders
✗ Separate from main backlog
✗ No prioritization
✗ All debt same severity