Technical debt prompts are useful when they connect a design problem to a cost the team actually experiences. A complicated module may be expensive because every feature changes it, or it may be stable code nobody needs to touch. Those situations deserve different priorities. The prompts below help build an evidence-based inventory, compare repair options and define small changes whose effects can be checked.
Begin with recurring friction
Choose a concrete problem such as a slow release check, repeated authorization defects or a module that requires coordinated edits across many features. Supply examples, relevant code paths and constraints on change. Avoid asking for a repository-wide score without a decision it will inform. A numeric grade can look precise while hiding subjective preferences about structure.
Martin Fowler's technical debt quadrant distinguishes deliberate and inadvertent debt alongside prudent and reckless choices. It is a useful vocabulary for discussion, not a formula for ranking your backlog. These prompts use original questions about observed impact, repair cost and evidence of improvement.
Build an inventory with a reason to care
Ask the agent to name a specific design condition, show where it appears and connect it to an observed consequence. Keep suspected issues separate from confirmed ones. A warning about possible future scale should not be presented with the same confidence as repeated failed releases. Include the cost of leaving the condition unchanged for another release cycle.
Assess technical debt related to {{recurring_problem}}.
Evidence: {{delivery_or_incident_examples}}. Scope: {{code_paths}}.
For each finding give the design condition, concrete location, observed
cost, confidence and consequence of deferral. Separate evidence-backed
findings from hypotheses. Do not rank style preferences as operational
problems or invent hours saved by a proposed refactor.
Compare a small repair with larger alternatives
A rewrite can remove one kind of complexity while creating migration risk. Ask for at least one bounded option that addresses the current pain. Include testability and operational ownership in the comparison. The best next step may be a measurement, a contract test or a small boundary change rather than replacing a subsystem.
Compare ways to address {{debt_finding}} under {{constraints}}.
Include a minimal repair, a larger redesign and deferral.
For each, explain the affected behavior, migration risk, dependencies,
verification effort and expected benefit as an explicit hypothesis.
Recommend the smallest step that tests the important assumption.
Keep the existing user contract visible throughout the proposal.
Turn a finding into a finishable task
A task should have a boundary someone can review. Ask which behavior stays stable, which measurable problem should improve and what evidence will close the work. Split preparatory tests from implementation only when that sequence helps manage real risk. Avoid a permanent cleanup ticket that expands every time someone opens the file.
Turn {{selected_debt_item}} into one implementation task.
Define scope, behavior to preserve, acceptance checks and a stop condition.
Use {{baseline_evidence}} to choose a meaningful before/after comparison.
List follow-up work separately. Draft a reviewer-friendly description
that explains the concrete problem and expected result without promising
unmeasured performance or delivery gains.
Review whether the change helped
After the repair, compare the same workflow or failure mode with the baseline. Record any new maintenance burden as well as the improvement. If the expected benefit did not appear, update the finding rather than treating merged code as proof of success. Keep the review proportional to the task's size and impact.
Save the approved debt-review prompt in Kipt with variables for friction, evidence and scope. When a repair changes a long-lived architecture choice, use the ADR prompts to preserve the decision and its tradeoffs.