A Technical Debt Triage Prompt for Engineers, Not Slide Decks

Technical debt conversations usually end one of two ways. Either nothing gets fixed because there's no business case, or everything gets a JIRA ticket and the backlog swells to 200 items nobody will ever touch. Both failures come from the same root: no shared way to decide what's worth fixing now.

A technical debt triage prompt gives you that shared method. Feed it the debt items, score each by risk and effort and churn, and get back a sequenced plan: fix these three this sprint, defer these, delete these tickets entirely. The output is engineer-facing, anchored to files and fixes, not a slide for leadership.

This is the prompt, the scoring contract, and where it diverges from the prioritization templates already out there.

Why most tech-debt prompts are aimed at the wrong reader

The good existing template, pmtoolkit's technical debt prioritization, is genuinely structured: modified RICE scoring, Fowler's debt quadrant, cost-of-inaction projections. But it's built for product managers and technical leaders making a business case to secure capacity. Its output is a 1,400-word document with velocity-tax calculations and roadmap phases. Useful for a leadership pitch. Useless when you're an engineer with two days and a directory of debt to sequence.

The tool roundups, like 8 AI tools for technical debt, point you at detection and remediation platforms but don't hand you a triage method you can run on your own list.

The gap is an engineer-facing triage prompt: code-level items, scored by the things engineers actually weigh (blast radius, change frequency, effort), sequenced into a plan you can start on after lunch. No business case required.

What you can do with this prompt

• Take a raw list of debt items and get each scored and ranked.
• Sequence a remediation plan that fits the time you actually have.
• Identify the debt that's safe to ignore, so the backlog shrinks instead of grows.
• Tie each item to a file and a concrete fix, not a vague theme.
• Justify the order to a skeptical lead with a transparent score, not a vibe.
• Re-triage after a sprint as priorities shift.

Anatomy of the prompt

The score is the spine: risk times change frequency, divided by effort. The contract forces every item through it.

Role:    You are a staff engineer triaging technical debt in {{codebase_area}}.
Context: {{debt_items}} — each with a file/location and a short description.
         {{change_frequency}} — which files change often (from git history).
Task:    Score each item: risk (1-5), change frequency (1-5), effort (1-5).
         priority = (risk x change_frequency) / effort.
         Flag any item that's safe to defer indefinitely.
Output:  A table — Item | Location | Risk | Churn | Effort | Priority | Action.
         Sorted by priority. End with a 3-item "do this sprint" shortlist.

Step-by-step usage

1. Gather inputs

List the debt items, each with a file and one-line description. Pull change frequency from git: how many commits touched each file in the last few months. That number does most of the prioritization work.

2. Fill variables

Set {{codebase_area}}, {{debt_items}}, and {{change_frequency}}. The more honest the effort estimates, the more useful the ranking.

3. Run the prompt

Read the "do this sprint" shortlist first. If it lists items in code that never changes, your churn data didn't make it in. Re-run with it.

4. Post-process

Sanity-check the top three against the release you're shipping. The prompt optimizes for leverage; you optimize for what unblocks the next feature.

5. Iterate

After the sprint, re-triage with the remaining items and updated churn. Debt priorities move as the code moves.

Prompt-craft patterns

Make effort a real number, not a feeling. Ask the model to estimate effort in rough hours or t-shirt sizes and to state its assumption. An effort score pulled from nowhere makes the priority math noise.

For each item, estimate effort as S (< half a day), M (1-2 days),
L (> 2 days), and state the one assumption driving the estimate.

Force a "defer or delete" verdict. The most valuable output is permission to close tickets. Tell the prompt to flag items whose cost-of-inaction is effectively zero, and watch the backlog shrink.

Anchor every item to a location. "Improve error handling" is a wish. "Wrap the three bare except blocks in payments/refund.py" is a task. The contract should reject items that don't name a file.

A note on model behavior here: Claude holds the scoring rubric across a long item list and applies it consistently, where GPT-4o sometimes re-anchors its severity scale halfway down and starts grading on a curve. If the bottom half of the table looks softer than the top, that's the tell. Restate the rubric near the end of the prompt, or run the list in two halves and merge. Either fixes it.

The take: a technical debt backlog over about 30 items is a graveyard, not a plan, and the highest-leverage move is usually deleting two-thirds of it. Most debt tickets describe code that works, isn't changing, and will never be worth the regression risk to refactor. Triage isn't about ranking all of it. It's about admitting most of it doesn't matter and protecting your attention for the debt that's actively slowing the team down.

Variables you'll set

Getting started

1. Collect the debt items with file locations.
2. Run a git log aggregation for per-file change frequency.
3. Fill {{debt_items}} and {{change_frequency}}.
4. Read the shortlist and delete the deferred tickets for real.
5. Sanity-check the top three against the next release.
6. Re-triage each sprint as the code moves.
7. When debt sits in code nobody understands, the Legacy Code Comprehension Harness tells you what the module does before you score it.

Triage tells you what to fix; the next steps tell you how to fix it safely. Two reads: detecting the code smells that become debt so you catch it earlier, and a repo health scorecard to track whether the debt is shrinking over time. For the diffs where new debt sneaks in, the Code Review Policy System Prompt keeps maintainability a required review dimension.