How much time should we spend on tech debt?

A common allocation is 15-25% of capacity, higher in legacy-heavy contexts and lower in pure greenfield. Track it so it does not silently drift to 0%.

Should AI choose priorities?

No — AI scores, humans decide. The model cannot see hiring plans or customer commitments, so feed those in and treat the output as a draft ranking.

What is "Compounding" debt?

Debt where fixing later costs materially more than fixing today — a schema being widened weekly, or a growing dependency on a deprecated library. It maps to high Time Criticality in WSJF.

How do I justify cleanup with no immediate revenue?

Use template 8's cost-of-delay model and convert the result to dev-velocity hours or risk exposure (e.g., outage probability), which leadership can price.

Which model handles a whole-repo debt audit?

As of June 2026, any 1M-context model — Claude Opus 4.7, Sonnet 4.6, or Gemini 3.1 Pro — can hold a mid-size repo. For an agentic audit that opens files itself, run the prompts through Claude Code.

When should I rewrite?

Almost never. Try sunset, then refactor first. A full rewrite is typically a multi-year detour that re-creates the same debt under new names.

Prompt Library

Technical Debt Prioritization Prompts: 12 Templates Beyond a Backlog

12 prompt templates to rank tech debt by impact × effort × decay risk — mapped to WSJF, with model picks for June 2026.

Published: May 19, 2026 Updated: Jun 14, 2026 Author: AI Productivity Guide Team 🌐 查看中文版本

Every backlog has a “tech debt” tag with 50 tickets nobody touches. The fix is not another grooming session — it is a scoring function. A good prioritization prompt ranks each item by impact, effort, and decay risk, then hands you at most five things worth funding this quarter. The 12 templates below do exactly that, and they map cleanly onto the WSJF (Weighted Shortest Job First) economics used in SAFe.

TL;DR

Score debt by (impact + time-criticality + risk) ÷ effort — that is WSJF, restated. Rank, then fund the top 5.
Track DECAY separately from impact: “Compounding” debt gets more expensive every month you wait, so it jumps the queue even at low impact today.
AI scores; humans decide. The model cannot see your hiring plan, customer commitments, or the EU launch on the roadmap — feed those in as context.
Run these on a 1M-token model so it can read the whole repo: Claude Opus 4.7 or Sonnet 4.6 (1M context, June 2026), Gemini 3.1 Pro (1M), or GPT-5.5. For repo-wide audits, drive them through Claude Code.
Cap quarterly debt at ~15-25% of capacity; never fund more than 5 items at once or none ship cleanly.

Who this is for

Tech leads writing a quarterly tech-debt plan, founders deciding whether to spend a sprint on cleanup, and engineers building a budget case for a refactor.

How this maps to WSJF

The classic SAFe formula is Cost of Delay ÷ Job Size, where Cost of Delay is User-Business Value + Time Criticality + Risk Reduction, each scored on a modified Fibonacci scale (1, 2, 3, 5, 8, 13, 20). The templates here use the same shape with debt-friendly names:

WSJF term	Prompt term	What it captures
User-Business Value	IMPACT	User-visible pain + dev-velocity drag
Time Criticality	DECAY	How fast the cost grows if untouched
Risk Reduction	risk dimension of IMPACT	Outage, security, compliance exposure
Job Size	EFFORT	S / M / L weeks to fix

If your org already runs WSJF, score debt in the same batch as features so the two compete on one list. If not, the impact × decay ÷ effort version is lighter and still defensible to leadership. See SAFe’s WSJF reference for the canonical definition.

When not to use these prompts

Don’t use them to justify a rewrite — that is a separate conversation. Don’t run them without business context (revenue, deadlines, hiring); a model with no roadmap will optimize for code beauty, not money.

Which model to run these on (June 2026)

Tech-debt scoring rewards a model that can hold the whole codebase at once. As of June 2026:

Model	Context	Best for
Claude Opus 4.7	1M tokens	Cross-module decay analysis, dependency tracing (SWE-bench Verified 87.6%)
Claude Sonnet 4.6	1M tokens	The everyday workhorse — cheaper, still 1M context
Gemini 3.1 Pro	1M tokens	Largest single-prompt repo dumps
GPT-5.5	up to 1M (full window on ChatGPT $200 Pro)	Long agentic audit runs (Terminal-Bench 2.0 82.7%)

For an interactive repo audit, run these prompts inside Claude Code (Anthropic models only) so the model can open files itself rather than relying on a paste. If you only need the ranking and have the items already listed, any of the four above works fine in a single chat.

Prompt anatomy

Every prioritization prompt should carry six elements:

Role: who the model plays (SRE, release captain, staff engineer, QA lead).
Context: stack, branch, failing logs, diff, dashboard URL, plus roadmap facts (hiring, launches, EOL dates).
Goal: one concrete deliverable — a ranked table, ticket list, runbook, or one-page plan.
Constraints: what the model must not do (don’t auto-fix, don’t invent file paths, don’t recommend a rewrite).
Output format: numbered findings, markdown table, JSON, or unified diff.
Signal: 1-2 “good” output examples, or a counter-example to steer away from.

12 copy-ready prompt templates

1. Score by impact × effort × decay

Score each debt item: (a) IMPACT (1-5): user-visible / dev-velocity / risk, (b) EFFORT (S / M / L weeks), (c) DECAY (Stable / Growing / Compounding). Final score = IMPACT × DECAY weight ÷ EFFORT. Output a ranked table. Treat any "Compounding + L effort" specially — those eat the future.

2. “Why now” filter

For each debt item, answer: "What changes in the next 90 days that makes this urgent?" (e.g., hiring 3 backend devs, launching to enterprise, EU rollout, framework EOL). Drop items whose answer is "nothing".

Cluster these [nItems] debt items into themes. For each theme: top 1-2 items + bundled cleanup that can ride along. Bundling cuts overhead — but only if items share files / mental model. Don't bundle unrelated items.

Variable to swap: [nItems]

4. Sunset candidates

Identify code / features eligible for sunset: (1) Low usage + high maintenance cost, (2) Replaced internally but never removed, (3) Behind a feature flag that's been on for > 12 months. Output: candidates + a decommission plan.

5. Onboarding-friction debt

Audit debt that slows new-hire onboarding: (1) Undocumented build steps, (2) Magic env vars, (3) Local dev requires manual seed, (4) "Just ask [person]" knowledge. Prioritise the items that block a new hire in the first week.

Variable to swap: [person]

6. Velocity-impact debt

Audit debt that slows weekly velocity: (1) Tests > 10 min, (2) PRs that need 3+ approvals due to ownership ambiguity, (3) Build flake > 5%, (4) Areas of code requiring "specialist" review. Output top 3 + ROI estimate.

7. Risk-led debt

Audit debt that creates production risk: (1) Single points of failure, (2) Manual deploy steps, (3) No rollback for X service, (4) Logs missing for critical path, (5) Off-team-owned code blocking incident response. Severity-rank.

8. Cost-of-delay model

For 5 candidate debts, estimate cost-of-delay: (a) Pain today (hours / quarter), (b) Pain in 1 year if untouched, (c) Fix cost. Output ROI = (FuturePain - TodayPain) / FixCost. Recommend top 3 to fund this quarter.

9. Tech-debt narrative for leadership

Take these 3 prioritized items and write a 200-word narrative for a product / business audience: (1) Each item in plain language, (2) Business consequence if untouched, (3) Engineering investment + outcome, (4) Why now. No jargon.

10. Anti-bundle: stop merging fixes into features

Audit the last 10 feature PRs for hidden cleanup. List places where cleanup was bundled, making the PR harder to review. For each: extract the cleanup into a follow-up ticket. Output ticket drafts.

11. Debt freeze plan

We can't fix this quarter — design a debt FREEZE plan: (1) Areas we'll stop adding to until cleaned up, (2) Compatibility shims to keep new features off the bad code, (3) Comms to the team. Output a 1-page plan.

12. Post-mortem → debt items

Convert this post-mortem into 1-3 debt tickets: title, problem, acceptance criteria, owner, decay class. Don't re-litigate the incident — focus on prevention.

A worked example

Feed template 1 four real items and a model returns a table like this. The point is what the ranking surfaces, not the exact numbers:

Item	IMPACT	EFFORT	DECAY	Score	Verdict
Auth lib 2 majors behind (EOL Q4)	3	M	Compounding	High	Fund now — decay flips it above flashier work
Flaky CI (8% failure)	4	S	Growing	High	Fund — cheap and bleeds the whole team
Rewrite legacy reporting module	5	L	Stable	Low	Defer — high pain but stable; not this quarter
Tidy logging format	2	S	Stable	Low	Skip — nice-to-have, no decay

The reporting rewrite “feels” like the biggest item, but stable + L effort sinks it. The auth upgrade looks boring until DECAY (a hard EOL) pushes it to the top. That inversion is the entire value of the prompt.

Common mistakes

Treating loudness as priority — the most upset engineer is not always right.
No effort estimate — every item then looks “important”.
No decay model — Compounding debt is silent and expensive.
Funding more than 5 items per quarter — none ship cleanly.
No business framing — leadership won’t fund what it can’t understand.
Bundling a debt fix into a feature PR — the reviewer sees neither clearly (see refactor scope too broad).
Forgetting to sunset replaced code — it haunts the repo forever.

How to push results further

Score DECAY explicitly; Stable debt can wait, Compounding cannot.
5 items max per quarter — anything more is wish-listing.
Bundle related items, but never bundle a feature and a cleanup in the same PR.
Make the cost-of-delay model visible to leadership in dollars or velocity hours.
Re-run prioritization every quarter — context changes faster than the backlog.
Name a single owner and a deadline per item.
Order of preference: sunset > refactor > tolerate. Rewrite is almost always a multi-year detour.

FAQ

How much time should we spend on tech debt?: A common allocation is 15-25% of capacity, higher in legacy-heavy contexts and lower in pure greenfield. Track it so it does not silently drift to 0%.
Should AI choose priorities?: No — AI scores, humans decide. The model cannot see hiring plans or customer commitments, so feed those in and treat the output as a draft ranking.
What is “Compounding” debt?: Debt where fixing later costs materially more than fixing today — a schema being widened weekly, or a growing dependency on a deprecated library. It maps to high Time Criticality in WSJF.
How do I justify cleanup with no immediate revenue?: Use template 8’s cost-of-delay model and convert the result to dev-velocity hours or risk exposure (e.g., outage probability), which leadership can price.
Which model handles a whole-repo debt audit?: As of June 2026, any 1M-context model — Claude Opus 4.7, Sonnet 4.6, or Gemini 3.1 Pro — can hold a mid-size repo. For an agentic audit that opens files itself, run the prompts through Claude Code.
When should I rewrite?: Almost never. Try sunset, then refactor first. A full rewrite is typically a multi-year detour that re-creates the same debt under new names.

Tags: #Prompt #Coding #Tech debt #Refactor