Technical Debt Management

Pathrule1 Rule • 2 Memories • 1 Skill

Technical debt management makes intentional tradeoffs visible without labeling every imperfection as debt. This bundle records the decision, affected boundary, current cost, risk, owner, review trigger, and retirement options, then prioritizes work from delivery and reliability evidence. Unlike Code Review, it governs accumulated system tradeoffs over time rather than deciding whether one change is ready to merge.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

docs/

engineering/

debt/

Every debt record names cost, owner, trigger, and exit

Debt priority comes from interest and risk, not age alone

triage-technical-debt

src/

Pay debt at the smallest stable seam

Rules

Every debt record names cost, owner, trigger, and exit/docs/engineering/debtmediumstrictA debt item identifies the compromised boundary, evidence of cost or risk, accountable owner, review trigger, and smallest credible retirement path.

1	A ticket called refactor later is not a manageable obligation. Record the original decision or shortcut, affected paths and consumers, benefit received, present delivery or operational cost, failure risk, constraints, accountable owner, date introduced, review or expiry trigger, and options for retirement. Link measurements and incidents rather than using age or dislike as the only evidence.
2
3	- Distinguish intentional debt, discovered design weakness, obsolete dependency, missing test, migration gap, and ordinary defect.
4	- Define what would make the item more urgent, safe to close, or no longer relevant.
5	- Keep the scope small enough that one team can own the next decision and avoid umbrella items that hide unrelated work.
6	- Revisit debt when the named boundary changes, the trigger fires, or the review date arrives.
7
8	Verification: Sample open items and ask another engineer to explain impact, priority, owner, next action, and closure evidence without private context.

Memories

Debt priority comes from interest and risk, not age alone/docs/engineering/debtRepeated engineering time, change failure, incident exposure, security impact, customer friction, and blocked strategy determine payoff priority.

1	Old code can be stable and cheap, while a recent shortcut can tax every deployment. Estimate debt interest from repeated debugging, slow delivery, review burden, test instability, compute or vendor cost, incident frequency, security exposure, compliance constraint, customer impact, and blocked product options. Use ranges and observable proxies when exact numbers are unavailable.
2
3	Compare payoff cost and risk with the expected avoided interest over a named horizon. Prioritize items at actively changing boundaries or with approaching triggers, and lower priority when usage or impact disappears. Review the portfolio by subsystem and owner so one visible codebase does not absorb the entire budget. See /src for the implementation boundary and /tests for the regression evidence needed after payoff.

Pay debt at the smallest stable seam/srcIncremental payoff isolates a boundary, preserves behavior with characterization evidence, migrates consumers, and deletes the old path last.

1	A full rewrite bundles discovery, behavior change, migration, and cleanup into one risky release. Find a stable seam around the costly behavior, capture current contracts and exceptions, add characterization tests or production evidence, then introduce the improved path behind an adapter, flag, or versioned interface. Move consumers in observable increments and compare outcomes.
2
3	Define rollback and dual-run limits before migration, avoid permanent synchronization between old and new models, and delete compatibility code when the last consumer leaves. Feature work should pay adjacent debt only when the boundary and verification are already in scope; otherwise create the owned record. See /docs/engineering/debt for the decision and /tests for the proof that enables deletion.

Skills

triage-technical-debt/docs/engineering/debtTurn a debt claim into a bounded decision using cost evidence, risk, ownership, triggers, payoff options, and closure proof.

1	---
2	name: triage-technical-debt
3	description: Triage a technical debt claim into an owned, evidence-backed payoff or acceptance decision.
4	---
5
6	# Triage Technical Debt
7
8	1. State the compromised boundary, affected paths and consumers, original tradeoff, current behavior, and why this is debt rather than a defect or preference.
9	2. Gather evidence of interest and risk from delivery time, incidents, failures, test instability, security, cost, customer impact, and blocked plans.
10	3. Identify owner, dependencies, expiry or review trigger, options to accept, contain, incrementally pay, replace, or retire, and the smallest stable seam.
11	4. Estimate payoff and migration risk, define characterization and regression evidence, and choose a priority against other owned work.
12	5. Record the decision and next review; on completion, remove obsolete paths, close linked exceptions, and attach before-and-after evidence.
13
14	Do not open an unbounded rewrite item when the next decision or first safe slice can be stated directly.

Why this pattern

Agents create vague cleanup tickets, expand feature work into opportunistic rewrites, or leave temporary shortcuts with no owner, trigger, cost evidence, or retirement condition.

Built for Engineering teams balancing feature delivery, reliability, maintainability, migration work, and deliberate architectural tradeoffs.

Keeps your assistant from:

Debt backlogs becoming unactionable lists of subjective complaints
Temporary exceptions becoming permanent because no trigger or owner exists
Large rewrites starting without measured cost, boundary, or incremental payoff

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25