Technical Debt Register Template

# Technical Debt Register

**Team/System:** [Name]
**Last Updated:** [Date]
**Owner:** [Name]

---

## Summary Dashboard

### Debt Overview

| Category | Count | Severity Score | Trend |
|----------|-------|----------------|-------|
| Architecture | [#] | [Score] | ↑↓→ |
| Code Quality | [#] | [Score] | ↑↓→ |
| Testing | [#] | [Score] | ↑↓→ |
| Dependencies | [#] | [Score] | ↑↓→ |
| Infrastructure | [#] | [Score] | ↑↓→ |
| Documentation | [#] | [Score] | ↑↓→ |
| Security | [#] | [Score] | ↑↓→ |
| **Total** | [#] | [Score] | |

### Debt Health Score

**Current Score:** [X] / 100 (higher is better)

**Target Score:** [X] / 100 by [Date]

### Key Metrics

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Total debt items | [#] | [#] | 🟢🟡🔴 |
| Critical items | [#] | 0 | 🟢🟡🔴 |
| Items added (this quarter) | [#] | | |
| Items resolved (this quarter) | [#] | | |
| Avg age of debt items | [Days] | <90 days | 🟢🟡🔴 |

---

## Debt Register

### [DEBT-001] [Title]

**Category:** [Architecture / Code Quality / Testing / Dependencies / Infrastructure / Documentation / Security]

**Severity:** 🔴 Critical / 🟠 High / 🟡 Medium / 🟢 Low

**Status:** Open / In Progress / Resolved / Won't Fix

**Created:** [Date]
**Updated:** [Date]
**Owner:** [Name]

#### Description

[What is the debt? Be specific.]

#### Impact

**Current impact:**
- [Impact 1 - e.g., "Adds 30 min to every deploy"]
- [Impact 2 - e.g., "Causes 2-3 bugs per sprint in X area"]

**Risk if not addressed:**
- [Risk 1 - e.g., "Will block scaling past 10K users"]
- [Risk 2 - e.g., "Security vulnerability in deprecated library"]

**Teams/systems affected:**
- [Team/System 1]
- [Team/System 2]

#### Root Cause

[How did this debt accumulate?]
- [ ] Deliberate trade-off
- [ ] Accidental/learning
- [ ] Bit rot
- [ ] Missing requirements

#### Remediation

**Proposed solution:**
[Description of how to fix]

**Effort estimate:** [T-shirt size or story points]

**Prerequisites:**
- [Prereq 1]
- [Prereq 2]

#### Metrics

| Metric | Before | Target | After |
|--------|--------|--------|-------|
| [Metric] | [Value] | [Value] | [Value] |

#### History

| Date | Event | Notes |
|------|-------|-------|
| [Date] | Created | [Initial context] |
| [Date] | Updated | [What changed] |

---

### [DEBT-002] [Title]

[Same structure as above]

---

## Debt by Category

### Architecture Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-001 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |
| DEBT-002 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

### Code Quality Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-003 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

### Testing Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-004 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

### Dependencies Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-005 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

### Infrastructure Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-006 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

### Documentation Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-007 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

### Security Debt

| ID | Title | Severity | Effort | Priority |
|----|-------|----------|--------|----------|
| DEBT-008 | [Title] | 🔴🟠🟡🟢 | [Size] | [P1/P2/P3] |

---

## Prioritization Matrix

### Severity × Effort Matrix

|  | Small Effort | Medium Effort | Large Effort |
|--|--------------|---------------|--------------|
| **Critical** | [IDs] - Do Now | [IDs] - Plan Now | [IDs] - Strategic |
| **High** | [IDs] - Quick Win | [IDs] - Plan | [IDs] - Evaluate |
| **Medium** | [IDs] - Backlog | [IDs] - Backlog | [IDs] - Maybe |
| **Low** | [IDs] - If Time | [IDs] - Probably Not | [IDs] - Don't |

### Prioritized Backlog

| Priority | ID | Title | Severity | Effort | Target |
|----------|-----|-------|----------|--------|--------|
| 1 | DEBT-001 | [Title] | 🔴 | M | Q4 2025 |
| 2 | DEBT-003 | [Title] | 🟠 | S | Q4 2025 |
| 3 | DEBT-002 | [Title] | 🟠 | L | Q1 2026 |

---

## Paydown Plan

### This Quarter

**Budget:** [X% of engineering time] = [Y story points / Z days]

**Goals:**
- [ ] Resolve [#] critical items
- [ ] Reduce total severity score by [X]%
- [ ] Address oldest items (>6 months)

**Planned Work:**

| ID | Title | Sprint | Owner | Status |
|----|-------|--------|-------|--------|
| DEBT-001 | [Title] | Sprint 14 | [Name] | Not Started |
| DEBT-003 | [Title] | Sprint 15 | [Name] | Not Started |

### Debt Budget Policy

**Allocation:** [X]% of each sprint dedicated to debt paydown

**Rules:**
1. Critical security debt: Address immediately (outside budget)
2. Every feature should leave code better than found
3. Debt added must be documented within sprint
4. Quarterly debt review with prioritization

---

## Trends and History

### Quarterly Trend

| Quarter | Items Start | Added | Resolved | Items End | Severity Score |
|---------|-------------|-------|----------|-----------|----------------|
| Q1 2025 | [#] | [#] | [#] | [#] | [Score] |
| Q2 2025 | [#] | [#] | [#] | [#] | [Score] |
| Q3 2025 | [#] | [#] | [#] | [#] | [Score] |
| Q4 2025 | [#] | [#] | [#] | [#] | [Score] |

### Resolved Items (Last 90 Days)

| ID | Title | Resolved Date | Impact |
|----|-------|---------------|--------|
| DEBT-XXX | [Title] | [Date] | [Measured impact] |

---

## Appendix

### Severity Definitions

| Severity | Definition | Examples |
|----------|------------|----------|
| 🔴 Critical | Blocking work, security risk, or causing incidents | Security vulnerability, system unstable |
| 🟠 High | Significant impact on velocity or quality | Major refactoring needed, frequent bugs |
| 🟡 Medium | Noticeable drag but manageable | Code harder to change, slower deploys |
| 🟢 Low | Minor inconvenience | Cosmetic, nice-to-have cleanup |

### Effort Definitions

| Size | Definition | Typical Duration |
|------|------------|------------------|
| XS | Trivial change | <1 day |
| S | Small, well-understood | 1-3 days |
| M | Medium complexity | 1-2 weeks |
| L | Large, may need design | 2-4 weeks |
| XL | Very large, strategic | >1 month |

### Process

**Adding debt:**
1. Anyone can add debt items
2. Fill out template completely
3. Initial triage by tech lead
4. Added to quarterly prioritization

**Reviewing debt:**
1. Weekly: Quick scan for new critical items
2. Monthly: Review progress on planned work
3. Quarterly: Full prioritization and planning

# Technical Debt Register

**Team/System:** Platform Team / Core Platform
**Last Updated:** October 15, 2025
**Owner:** Alex Rivera

---

## Summary Dashboard

### Debt Overview

| Category | Count | Severity Score | Trend |
|----------|-------|----------------|-------|
| Architecture | 3 | 18 | → |
| Code Quality | 5 | 12 | ↓ |
| Testing | 4 | 10 | ↓ |
| Dependencies | 6 | 15 | ↑ |
| Infrastructure | 2 | 8 | → |
| Documentation | 3 | 6 | → |
| Security | 2 | 14 | ↓ |
| **Total** | 25 | 83 | ↓ |

### Debt Health Score

**Current Score:** 68 / 100 (higher is better)

**Target Score:** 80 / 100 by Q2 2026

### Key Metrics

| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Total debt items | 25 | <20 | 🟡 |
| Critical items | 2 | 0 | 🔴 |
| Items added (Q4) | 4 | <6 | 🟢 |
| Items resolved (Q4) | 7 | >6 | 🟢 |
| Avg age of debt items | 67 days | <90 days | 🟢 |

---

## Debt Register

### [DEBT-001] Monolithic Database Schema

**Category:** Architecture

**Severity:** 🔴 Critical

**Status:** In Progress

**Created:** 2025-03-15
**Updated:** 2025-10-10
**Owner:** Alex Rivera

#### Description

Our PostgreSQL database uses a single schema with 150+ tables, many with tight coupling. Foreign keys prevent independent service deployment, and schema migrations require coordinated downtime.

#### Impact

**Current impact:**
- Every schema migration requires 15-30 min downtime window
- Cannot scale individual services independently
- Database is bottleneck at 70% capacity
- All services coupled to same release cycle

**Risk if not addressed:**
- Will hit database limits at 2x current scale (~6 months)
- Major incident risk during migrations
- Prevents microservices architecture evolution

**Teams/systems affected:**
- All engineering teams
- All production services

#### Root Cause

- [x] Deliberate trade-off (MVP speed)
- [ ] Accidental/learning
- [x] Bit rot (grew beyond original design)
- [ ] Missing requirements

Original monolith design was appropriate for early stage. We've outgrown it but never invested in splitting.

#### Remediation

**Proposed solution:**
1. Identify service boundaries (done)
2. Extract user service with own database (in progress)
3. Extract orders service
4. Extract inventory service
5. Implement event sourcing for cross-service data

**Effort estimate:** XL (3-4 months total)

**Prerequisites:**
- Event infrastructure (Kafka) - Done
- Database-per-service pattern established
- Read replica for zero-downtime migration

#### Metrics

| Metric | Before | Target | After |
|--------|--------|--------|-------|
| Migration downtime | 15-30 min | 0 min | TBD |
| DB capacity utilization | 70% | <50% | TBD |
| Deploy independence | 0 services | 4 services | TBD |

#### History

| Date | Event | Notes |
|------|-------|-------|
| 2025-03-15 | Created | Identified during capacity planning |
| 2025-06-01 | Prioritized | Added to Q3 roadmap |
| 2025-08-15 | Started | User service extraction begun |
| 2025-10-10 | Updated | Phase 1 (read path) complete |

---

### [DEBT-002] Legacy Authentication Module

**Category:** Security

**Severity:** 🔴 Critical

**Status:** Open

**Created:** 2025-01-20
**Updated:** 2025-10-01
**Owner:** Mike Johnson

#### Description

Authentication module uses bcrypt with cost factor 10 (should be 12+), has no rate limiting on login attempts, and lacks support for modern auth flows (WebAuthn, passkeys). Session management uses JWTs without refresh token rotation.

#### Impact

**Current impact:**
- Below security best practices
- Cannot pass enterprise security audits
- Blocking SSO implementation for enterprise customers

**Risk if not addressed:**
- Credential stuffing attacks feasible
- Session hijacking possible
- $2.4M in enterprise pipeline blocked

**Teams/systems affected:**
- All users
- Enterprise sales
- Security team

#### Root Cause

- [x] Deliberate trade-off (built quickly 3 years ago)
- [x] Bit rot (security standards evolved)
- [ ] Accidental/learning
- [ ] Missing requirements

#### Remediation

**Proposed solution:**
Replace with Auth0 (separate build vs buy analysis completed, recommending buy).

**Effort estimate:** M (6-8 weeks with vendor)

**Prerequisites:**
- Auth0 contract signed (pending)
- Migration plan approved

#### Metrics

| Metric | Before | Target | After |
|--------|--------|--------|-------|
| Security audit findings | 4 critical | 0 critical | TBD |
| Enterprise deals blocked | 3 | 0 | TBD |

---

### [DEBT-003] Insufficient Test Coverage in Payments

**Category:** Testing

**Severity:** 🟠 High

**Status:** Open

**Created:** 2025-05-10
**Updated:** 2025-09-15
**Owner:** Emma Davis

#### Description

Payment processing code has 34% test coverage (team standard: 80%). Critical paths like refunds, partial payments, and error handling have minimal testing. We've had 3 payment bugs in production in the last 6 months.

#### Impact

**Current impact:**
- 3 payment-related bugs reached production (Q2-Q3)
- Engineers afraid to modify payment code
- Manual testing required for any payment changes
- Average 2 extra days per payment feature

**Risk if not addressed:**
- Customer financial impact from bugs
- Reputation damage
- Increased regulatory scrutiny

**Teams/systems affected:**
- Payments team
- Finance team
- Customer support

#### Root Cause

- [x] Deliberate trade-off (speed to market)
- [x] Accidental/learning (didn't understand complexity)
- [ ] Bit rot
- [ ] Missing requirements

#### Remediation

**Proposed solution:**
1. Add integration tests for all payment flows
2. Add unit tests for calculation logic
3. Implement contract tests with payment provider
4. Add property-based tests for edge cases

**Effort estimate:** M (3-4 weeks)

**Prerequisites:**
- Test environment with payment sandbox
- Test data fixtures

#### Metrics

| Metric | Before | Target | After |
|--------|--------|--------|-------|
| Test coverage | 34% | 85% | TBD |
| Payment bugs/quarter | 3 | 0 | TBD |
| Change lead time | +2 days | +0 days | TBD |

---

### [DEBT-004] Outdated React Version

**Category:** Dependencies

**Severity:** 🟡 Medium

**Status:** Open

**Created:** 2025-07-01
**Updated:** 2025-10-01
**Owner:** David Kim

#### Description

Frontend is on React 17, current version is React 19. Missing concurrent features, Server Components, and security patches. Class components still used in 40% of codebase.

#### Impact

**Current impact:**
- Cannot use React 19 features (Server Components, use() hook)
- Falling behind ecosystem (libraries dropping React 17 support)
- Technical interviews highlight outdated stack

**Risk if not addressed:**
- Libraries will drop support (6-12 months)
- Security patches not available
- Harder to hire frontend engineers

**Teams/systems affected:**
- Frontend team
- All customer-facing applications

#### Root Cause

- [ ] Deliberate trade-off
- [ ] Accidental/learning
- [x] Bit rot (time passed)
- [ ] Missing requirements

#### Remediation

**Proposed solution:**
1. Audit breaking changes (done)
2. Update to React 18 first
3. Migrate class components to hooks
4. Update to React 19
5. Adopt Server Components where appropriate

**Effort estimate:** L (6-8 weeks)

**Prerequisites:**
- All dependencies compatible with React 18+
- Testing infrastructure updated

---

## Prioritized Backlog

| Priority | ID | Title | Severity | Effort | Target |
|----------|-----|-------|----------|--------|--------|
| 1 | DEBT-002 | Legacy Authentication Module | 🔴 | M | Q4 2025 |
| 2 | DEBT-001 | Monolithic Database Schema | 🔴 | XL | Q1 2026 |
| 3 | DEBT-003 | Insufficient Test Coverage in Payments | 🟠 | M | Q4 2025 |
| 4 | DEBT-004 | Outdated React Version | 🟡 | L | Q1 2026 |

---

## Paydown Plan

### Q4 2025

**Budget:** 20% of engineering time = ~40 story points

**Goals:**
- [x] Resolve legacy auth (DEBT-002) via Auth0 migration
- [ ] Complete payments test coverage (DEBT-003)
- [ ] Continue database extraction (DEBT-001 Phase 2)

**Planned Work:**

| ID | Title | Sprint | Owner | Status |
|----|-------|--------|-------|--------|
| DEBT-002 | Legacy Auth | Sprint 14-16 | Mike | In Progress |
| DEBT-003 | Payment Tests | Sprint 15-16 | Emma | Not Started |
| DEBT-001 | DB Migration P2 | Sprint 14-17 | Alex | In Progress |

### Debt Budget Policy

**Allocation:** 20% of each sprint dedicated to debt paydown

**Rules:**
1. Critical security debt: Address immediately (outside budget)
2. Every feature should leave code better than found (Boy Scout Rule)
3. Debt added must be documented within sprint
4. Quarterly debt review with full team prioritization
5. No new features in areas with critical debt until addressed

---

## Trends and History

### Quarterly Trend

| Quarter | Items Start | Added | Resolved | Items End | Severity Score |
|---------|-------------|-------|----------|-----------|----------------|
| Q1 2025 | 22 | 8 | 5 | 25 | 95 |
| Q2 2025 | 25 | 6 | 4 | 27 | 92 |
| Q3 2025 | 27 | 5 | 6 | 26 | 88 |
| Q4 2025 | 26 | 4 | 5 | 25 | 83 |

**Trend:** Debt level stabilizing, severity decreasing. On track for target.

### Resolved Items (Last 90 Days)

| ID | Title | Resolved Date | Impact |
|----|-------|---------------|--------|
| DEBT-012 | Flaky CI tests | 2025-08-20 | CI failures reduced 80% |
| DEBT-015 | Missing API docs | 2025-09-05 | Support tickets reduced 30% |
| DEBT-008 | N+1 queries in dashboard | 2025-09-15 | Dashboard load time 3s → 0.5s |
| DEBT-019 | Deprecated logging library | 2025-10-01 | Logs now searchable in Datadog |
| DEBT-011 | Manual deployment steps | 2025-10-10 | Deploy time 45min → 15min |