Tech Debt Log

Tech Debt Log: {{PROJECT_NAME}}

Project: {{PROJECT_NAME}} Version: {{VERSION}} Date: {{DATE}} Author: {{AUTHOR}} Status: Draft | In Review | Approved Reviewers: {{REVIEWERS}}

Document History

Version	Date	Author	Changes
0.1	{{DATE}}	{{AUTHOR}}	Initial draft

1. Tech Debt Philosophy

Technical debt is not inherently bad. Sometimes taking on debt is the right business decision (shipping faster to meet a deadline). The problem is unacknowledged and unmanaged debt.

This log exists to:

Make invisible debt visible
Enable informed decisions about when to repay debt
Track the "interest" — how debt is slowing the team down
Demonstrate to stakeholders that quality is actively managed

Debt Entry Trigger: Any time you make a technical shortcut, write a workaround, defer a refactor, skip a test, or make a "we'll fix this later" comment — add an entry here.

2. Summary Dashboard

Metric	Current	Last Sprint	Trend
Total Items	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}
Open	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}
In Progress	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}
Resolved	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}
Critical / High (P1/P2)	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}
Debt in current sprint	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}
Avg age of open items (days)	{{DAYS}}	{{DAYS}}	{{↑/↓/→}}
Debt resolved this sprint	{{COUNT}}	{{COUNT}}	{{↑/↓/→}}

Sprint Debt Budget: {{X}}% of sprint capacity allocated to debt reduction (recommended: 15-20%)

3. Tech Debt Categories

Category	Description	Common Causes	Detection Method
Design	Architectural shortcuts, wrong abstractions, poor separation of concerns	Time pressure, evolving requirements	Code review, architecture review
Code Quality	Duplication, high complexity, poor naming, missing documentation	Speed over quality, lack of standards	Static analysis (SonarQube), code review
Infrastructure	Manual processes, missing monitoring, config drift, single points of failure	Growth outpacing ops maturity	Ops review, incident postmortems
Documentation	Missing or outdated technical docs, undocumented decisions, no onboarding guide	Documentation deferred, never caught up	New team member feedback, ops incidents
Dependency	Outdated libraries, deprecated APIs, unmaintained packages, version conflicts	Insufficient update cadence	Automated scan (Snyk/Dependabot)
Testing	Low coverage, flaky tests, missing integration tests, untested edge cases	Speed over quality	Coverage reports, incident analysis
Security	Known vulnerabilities not yet patched, security shortcuts taken	Urgency, lack of security knowledge	Security scans, CVE alerts
Performance	Known bottlenecks, inefficient queries, N+1 problems, no caching	Optimizations deferred	Performance monitoring, load tests

4. Impact Assessment Methodology

4.1 Impact Score (1–10)

Score	Impact Level	Effect on Team/Business
1–2	Negligible	Cosmetic; no measurable effect on velocity or product
3–4	Minor	Slightly slows specific tasks; <5% velocity impact
5–6	Moderate	Slows multiple tasks; 5–15% velocity impact; occasional bugs
7–8	High	Significantly slows development; 15–30% velocity impact; recurring bugs
9–10	Critical	Blocks progress; >30% velocity impact; high risk of production incidents

4.2 Effort to Fix (Story Points)

Size	Points	Typical Scope
XS	1	Single line / config change
S	2–3	Single function / component refactor
M	5–8	Module-level changes; cross-cutting update
L	13	Multi-module refactoring; architecture change
XL	21+	Major refactor; break into sub-tasks first

4.3 Priority Calculation

Priority = Impact Score × (1 / Effort) — High impact, low effort = P1

Priority	Criteria	Sprint Allocation Target
P1 — Critical	Impact ≥ 8 OR blocks release	Schedule within 1 sprint
P2 — High	Impact 6–7	Schedule within 2 sprints
P3 — Medium	Impact 4–5	Schedule within 4 sprints
P4 — Low	Impact ≤ 3	Schedule when convenient

5. Tech Debt Register

ID	Description	Category	Introduced	Impact (1-10)	Effort	Priority	Owner	Status	Target Resolution	Review Date	Notes
TD-001	{{DESCRIPTION}}	{{CATEGORY}}	{{DATE_OR_SPRINT}}	{{1-10}}	{{XS/S/M/L/XL}}	P{{1-4}}	{{@OWNER}}	Open	{{DATE}}	{{DATE}}	{{CONTEXT}}
TD-002		Code Quality						Open
TD-003		Testing						In Progress
TD-004		Architecture						Open
TD-005		Dependencies						Open
TD-006		Infrastructure						Open
TD-007		Documentation						Open
TD-008		Security						Open
TD-009		Performance						Open

Status Values: Open | In Progress | Resolved | Accepted (deferred) | Won't Fix (justified)

6. Prioritization Framework

6.1 Cost of Delay Analysis

ID	Description	Cost Per Sprint (velocity loss %)	Number of Sprints Open	Accumulated Cost
TD-001	{{DESCRIPTION}}	{{X}}%	{{COUNT}}	{{ACCUMULATED_COST}}

6.2 Debt Payoff Prioritization

When multiple P3 items compete for sprint capacity, use:

Quick wins first — Impact ≥ 5 AND Effort ≤ S (high ROI)
Blocker debt — Any item that blocks a planned feature
Aging debt — Items open > 3 sprints get auto-elevated one priority
Security debt — Always scheduled within 1 sprint regardless of impact score

7. Sprint Debt Allocation Guidelines

Team Velocity	Debt Budget (15%)	Recommended Items to Schedule
40 points/sprint	6 points	2–3 S items or 1 M item
60 points/sprint	9 points	3–4 S items or 1 M + 1 S
80 points/sprint	12 points	1 L item or 2 M items

Sprint Debt Review (each sprint planning):

PM + Tech Lead review open debt register (15 min)
Select debt items for sprint based on budget and priority
Add selected items to sprint backlog as technical tasks
Update status of in-progress items

8. Debt Reduction Tracking

Sprint	Debt Items Added	Debt Items Resolved	Net Change	Running Total Open
Sprint 1	{{COUNT}}	{{COUNT}}	{{+/-}}	{{COUNT}}
Sprint 2
Sprint 3

Debt Trend: {{INCREASING / STABLE / DECREASING}}

9. Trend Analysis

9.1 Debt by Category (this quarter)

Category	Items Added	Items Resolved	Net
Code Quality	{{COUNT}}	{{COUNT}}	{{+/-}}
Testing
Architecture
Dependencies
Infrastructure
Documentation
Security
Performance

9.2 Root Cause Analysis

Dominant category this quarter: {{CATEGORY}} Suspected root cause: {{ROOT_CAUSE}} Proposed systemic fix: {{FIX — hook/tool/process/rule}}

10. Resolved / Accepted Debt Archive

ID	Description	Resolution	Resolution Date	Sprint	Resolved By
TD-{{RESOLVED}}	{{DESCRIPTION}}	{{HOW_FIXED}}	{{DATE}}	Sprint {{X}}	{{@OWNER}}

Approval

Role	Name	Date	Signature
Author
Reviewer
Tech Lead
AI Director (John)