Tech Debt Tracker

tech-debt-tracker

Turn vague "this is messy" complaints into a ranked debt ledger with carrying-cost estimates and a repayment plan the team can execute. Frames debt as principal (the gap) plus interest (what we keep paying because the gap exists). Output is copy-paste ready; ticket / backlog write-back is user-gated.

When to use

• The user lists code smells, dead code, or "we should refactor X" and wants them turned into trackable items.
• A retro surfaced multiple debt complaints; the team needs them ranked, not all addressed at once.
• A new initiative is about to add features on top of debt; the team wants the carrying cost surfaced before committing.
• German triggers: "Tech-Debt-Liste", "wo bremst es uns?", "Aufräumen-Plan".

Do NOT use when:

• The user wants a single bug fixed — route to /bug-fix.
• The complaint is about process, not code (slow CI, noisy alerts) — surface as ops debt, not code debt; consider escalating to PO.
• The "debt" is actually a missing feature — route to po-discovery.

Procedure

1. Inspect inputs and collect candidate debt items

Read the input (retro notes, code-review threads, pasted complaints, agent observations). Analyze each source for one candidate per bullet, no editing yet.

2. Classify each item

Items spanning two classes split into two entries — never merge.

3. Estimate principal and interest

For each item:

• Principal — rough effort to repay (S / M / L; days, not hours).
• Interest — what we keep paying every week / sprint / month because the debt exists. Quantify or mark unknown (unknown interest is itself a finding — surface it).

Carrying cost = interest × time-until-repaid. High principal + zero interest → leave it. Low principal + recurring interest → top of the queue.

4. Rank by interest ÷ principal

Sort descending. The top ten are the candidates. Items below the top ten get a single line each (so they are not lost) but no deeper analysis — debt-list bloat is itself a debt.

5. Shape a repayment plan

For the top 3-5 items:

• Repayment shape — single PR · multi-PR series · campaign · re-architecture.
• Owner role — engineering · ops · PO · platform team.
• Trigger — what makes us pay this next (e.g. "before adding feature X", "when test runtime > 10 min", "next quarterly").

Items without a trigger sit forever. A trigger that is "someday" is no trigger — push back.

6. Issue a verdict

7. Validate the ledger

Verify before emitting: every top item has a class, principal, interest (or unknown), trigger, and owner; the ranking matches interest ÷ principal; tail items have one line each. Ensure no "someday" triggers and no agent-owned repayment owners slipped in.

Output format

The ledger is a single block with these ordered fields:

1. Inventory: — count and classes touched
2. Top items: — numbered list ranked by interest ÷ principal, each with class, principal, interest, trigger, owner, shape
3. Tail: — one-line bullets for tracked-but-deferred items
4. Verdict: — exactly one of track / pay-now / block
5. Next: — handoff target (/adr-create or backlog write-back)

Tech-Debt Ledger
Inventory: <count> items, <classes touched>

Top items (interest ÷ principal):
  1. [arch] <item>             Principal: M  Interest: high (3 hrs/sprint)
        Trigger: <condition>  Owner: <role>  Shape: <PR / series / campaign>
  2. [code] <item>             Principal: S  Interest: med  ...
  ...

Tail (tracked, no immediate action):
  - <item>
  - <item>

Verdict: track | pay-now | block
Next:    /adr-create (if a tradeoff lock is needed) | backlog write-back

Gotcha

• "Refactor X" is not a debt item — it is a wish. The item must name the gap and what it costs.
• Interest the team cannot measure is real but invisible. Mark unknown and ask a probe ("how often do you hit this?") rather than inventing a number.
• A debt list with no trigger is paperwork. Reject items the team has no plan to ever repay.

Do NOT

• Do NOT enumerate every smell in the codebase — the top ten plus a tail is the contract.
• Do NOT propose repayment owners the agent itself owns; debt repayment belongs to a human role.
• Do NOT push items into Jira / Linear without explicit ask; output is copy-paste ready, write-back is gated.
• Do NOT silently inflate principal estimates to discourage repayment the team should do.