Produce a complete technical debt register for a team or service. A debt register is not a complaint list — it is a prioritized, business-impact-aware inventory that lets an engineering team make deliberate choices about which debt to pay down, in what order, and with what expected return.
Good debt management is not eliminating all debt. It is ensuring debt is visible, owned, and resolved when the interest cost exceeds the cost of fixing it.
Ask for these if not already provided:
Team: [Name] | Service(s): [Name(s)] Author: [Name] | Last updated: [Date] Planning period: [Q[X] [Year]] | Review cadence: [Monthly / Quarterly]
[2–3 sentences describing the team's current debt situation, the main categories of debt, and the business context — e.g. are they in a growth phase where velocity matters, or approaching a compliance deadline where security debt is critical?]
Total items in register: [X] Unresolved items: [X] Critical/High priority items: [X] Estimated total resolution effort: [X story points / X engineer-weeks]
| Category | Description | Examples |
|---|---|---|
| Code quality | Code that works but is hard to change safely | Duplicated logic, deeply nested conditionals, inconsistent error handling, missing abstraction |
| Architecture | Structural decisions that limit scalability or increase coupling | Monolith that should be decomposed, sync calls that should be async, missing domain boundaries |
| Testing | Gaps in test coverage that increase regression risk | Missing unit tests, no integration tests, flaky test suite, no test data management |
| Security | Known vulnerabilities or missing security controls | Outdated dependencies with CVEs, missing rate limiting, hard-coded secrets, insufficient auth |
| Dependencies | Outdated or risky external dependencies | End-of-life libraries, major version lag, abandoned packages |
| Infrastructure | Infrastructure that limits reliability or developer productivity | Manual deployment steps, no IaC, single-AZ, missing autoscaling |
| Observability | Gaps in visibility that slow incident response | Missing metrics, no distributed tracing, poor log structure, no alerting on key SLIs |
| Process | Manual or error-prone operational processes | Manual DB migrations, no runbooks, tribal knowledge not documented |
Business impact (1–5):
Effort to resolve (1–5, lower = easier):
Priority score = Business impact × (6 − Effort) (rewards high-impact, low-effort items)
| ID | Item | Category | Business impact (1–5) | Effort (1–5) | Priority score | Status | Owner |
|---|---|---|---|---|---|---|---|
| TD-001 | [e.g. No integration tests for payment flow] | Testing | 5 | 3 | 15 | Open | [Name] |
| TD-002 | [e.g. Authentication library 3 major versions behind] | Security | 5 | 2 | 20 | Open | [Name] |
| TD-003 | [e.g. Database queries not using connection pooling] | Architecture | 4 | 2 | 16 | Open | [Name] |
| TD-004 | [e.g. Manual deployment process for [service]] | Infrastructure | 4 | 3 | 12 | In progress | [Name] |
| TD-005 | [e.g. 200-line God function in order processing] | Code quality | 3 | 3 | 9 | Open | [Name] |
| TD-006 | [e.g. No structured logging — plain text only] | Observability | 3 | 2 | 12 | Open | [Name] |
| TD-007 | [e.g. ORM version has known N+1 query issue] | Dependencies | 3 | 3 | 9 | Open | [Name] |
| TD-008 | [e.g. No runbook for [critical operation]] | Process | 3 | 1 | 15 | Open | [Name] |
| TD-009 | [e.g. Test coverage at 34% — no meaningful safety net] | Testing | 4 | 4 | 8 | Open | [Name] |
| TD-010 | [e.g. Hard-coded config values in application code] | Code quality | 2 | 1 | 10 | Open | [Name] |
| TD-011 | [e.g. Service deployed single-AZ with no failover] | Infrastructure | 5 | 4 | 10 | Open | [Name] |
| TD-012 | [e.g. No alerting on P95 latency for [endpoint]] | Observability | 4 | 1 | 20 | Open | [Name] |
Category distribution (by item count):
─────────────────────────────────────────────
Code quality ████████░░ [X items] ([X]%)
Architecture ██████░░░░ [X items] ([X]%)
Testing █████████░ [X items] ([X]%)
Security ████░░░░░░ [X items] ([X]%)
Dependencies ███░░░░░░░ [X items] ([X]%)
Infrastructure ████░░░░░░ [X items] ([X]%)
Observability ████░░░░░░ [X items] ([X]%)
Process ██░░░░░░░░ [X items] ([X]%)
─────────────────────────────────────────────
Priority distribution:
Critical (score 20–25): [X items]
High (score 12–19): [X items]
Medium (score 6–11): [X items]
Low (score 1–5): [X items]
Priority score: [Score] | Category: [Category] | Owner: [Name]
Problem: [2–3 sentences describing what the debt is, how it manifests, and what pain it currently causes. Be specific — reference actual incidents, slowdowns, or risks.]
Business impact: [What happens if this is not resolved? Reference any incidents, near-misses, or growth blockers. E.g. "This caused 2 production incidents in the last quarter and adds ~30 minutes of debugging time to any change in this area."]
Resolution approach:
[Clear description of the fix. Not "improve the code" — describe the actual work: "Extract the payment processing logic into a dedicated PaymentService class, write unit tests to 80% coverage, and update the 3 call sites."]
Steps:
Acceptance criteria:
Effort estimate: [X story points / X days] Suggested sprint: [Q[X] Sprint [Y] / When [dependency] is complete]
Priority score: [Score] | Category: [Category] | Owner: [Name]
Problem: [Description]
Business impact: [Impact description]
Resolution approach: [Approach description]
Steps:
Acceptance criteria:
Effort estimate: [X story points / X days] Suggested sprint: [Sprint or timeframe]
(Follow same format as above)
(Follow same format as above)
(Follow same format as above)
| Quarter | Focus area | Items targeted | Estimated capacity | Expected outcome |
|---|---|---|---|---|
| [Q1 Year] (current) | Security + observability | TD-002, TD-012, TD-006 | [X] points / [Y] eng-days | Auth library current; latency alerting live; structured logging shipped |
| [Q2 Year] | Architecture + reliability | TD-003, TD-011, TD-004 | [X] points / [Y] eng-days | Connection pooling fixed; multi-AZ deployed; deploy automation complete |
| [Q3 Year] | Testing coverage | TD-001, TD-009 | [X] points / [Y] eng-days | Payment flow integration tests live; overall coverage ≥60% |
| [Q4 Year] | Code quality + process | TD-005, TD-008, TD-010 | [X] points / [Y] eng-days | God functions refactored; runbooks complete; zero hard-coded config |
Sprint capacity: [X] story points
Allocation:
├── Feature work: [X * 0.75 = ~Y] points (75%)
├── Debt resolution: [X * 0.15 = ~Y] points (15%)
└── Unplanned/bugs: [X * 0.10 = ~Y] points (10%)
Debt items that fit in one sprint ([≤Y] points each):
✓ TD-002 ([X] points)
✓ TD-012 ([X] points)
✓ TD-006 ([X] points)
✓ TD-008 ([X] points)
Multi-sprint debt items (break into phases):
~ TD-001: Phase 1 ([X] pts) → Phase 2 ([X] pts)
~ TD-009: Requires dedicated debt sprint or pairing
Items where the cost of remediation currently exceeds the business value, accepted with explicit review dates.
| ID | Item | Reason for deferral | Review date | Owner |
|---|---|---|---|---|
| TD-XXX | [Item] | [e.g. "Rewrite would require 3 weeks with no user-facing value at current scale; revisit at 10× traffic"] | [Date] | [Name] |
| TD-XXX | [Item] | [e.g. "Dependency has a CVE but no upgrade path exists until Q3; mitigated by WAF rule"] | [Date] | [Name] |
Policy: No item may be deferred more than twice without escalation to the engineering manager.