Technical Debt Register

Technical Debt Register Skill

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.

Required Inputs

Ask for these if not already provided:

• Team or service name — what team and/or service this register covers
• Known debt items — list of known technical debt, or ask Claude to elicit them by asking about: legacy code, missing tests, outdated dependencies, architectural shortcuts, manual processes, observability gaps, security backlogs
• Tech stack — language, frameworks, infrastructure (helps Claude categorise and score items correctly)
• Team size and velocity — number of engineers and approximate story points or days per sprint (needed for effort estimates)
• Current quarter / planning period — so the roadmap targets the right timeframe

Output Format

Technical Debt Register: [Team / Service Name]

Team: [Name] | Service(s): [Name(s)] Author: [Name] | Last updated: [Date] Planning period: [Q[X] [Year]] | Review cadence: [Monthly / Quarterly]

Overview

[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]

Debt Category Definitions

Debt Register

Scoring Method

Business impact (1–5):

• 5 — Blocking growth, causing production incidents, or creating compliance risk
• 4 — Significantly slowing delivery or increasing incident likelihood
• 3 — Noticeable slowdown; manageable but accumulating
• 2 — Minor friction; low immediate risk
• 1 — Cosmetic or aspirational; no current business impact

Effort to resolve (1–5, lower = easier):

• 1 — <0.5 day; single engineer
• 2 — 0.5–2 days; single engineer
• 3 — 3–5 days; single engineer or small pair
• 4 — 1–2 weeks; team collaboration required
• 5 — >2 weeks; significant planning and coordination

Priority score = Business impact × (6 − Effort) (rewards high-impact, low-effort items)

Category Breakdown

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]

Top 5 Priority Items — Resolution Plans

TD-XXX: [Highest priority item name]

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:

1. [Specific, ticketable step]
2. [Specific, ticketable step]
3. [Specific, ticketable step]

Acceptance criteria:

• [Measurable criterion — e.g. "Zero hard-coded config values remain in application code"]
• [Measurable criterion — e.g. "CI pipeline passes with new tests"]
• [Measurable criterion]

Effort estimate: [X story points / X days] Suggested sprint: [Q[X] Sprint [Y] / When [dependency] is complete]

TD-XXX: [Second priority item name]

Priority score: [Score] | Category: [Category] | Owner: [Name]

Problem: [Description]

Business impact: [Impact description]

Resolution approach: [Approach description]

Steps:

1. [Step]
2. [Step]
3. [Step]

Acceptance criteria:

• [Criterion]
• [Criterion]

Effort estimate: [X story points / X days] Suggested sprint: [Sprint or timeframe]

TD-XXX: [Third priority item]

(Follow same format as above)

TD-XXX: [Fourth priority item]

(Follow same format as above)

TD-XXX: [Fifth priority item]

(Follow same format as above)

Debt Reduction Roadmap