Turn Technical Debt Into an Interest Register

Technical debt is not code a developer dislikes. It is a past shortcut with a recurring cost you can point to in incidents, slow changes, support work, or repeated mistakes.

This guide belongs to reel R089. Comment DEBT for the matching module and runnable starter.

Define the boundary before building

Input: debt item, original shortcut, affected code paths, recurring incidents, maintenance time, change frequency, owner, and delivery constraints.

Output: a debt register entry, measurable interest signals, repayment options, trigger threshold, bounded work plan, and review date.

The starter keeps exact checks in code and gives Claude only the reviewable drafting work. Dry-run is the default. Live mode can call Anthropic's Messages API, but it still returns a draft and performs no external action.

Paste this boundary into Claude Code before asking for implementation:

Workflow: Turn Technical Debt Into an Interest Register
Input: debt item, original shortcut, affected code paths, recurring incidents, maintenance time, change frequency, owner, and delivery constraints
Output: a debt register entry, measurable interest signals, repayment options, trigger threshold, bounded work plan, and review date

Map the trigger, strict input fields, deterministic code checks, Claude drafting step, approval gate, failure queue, and saved evidence. Use null for missing facts. Do not change code or call an external service yet.

The modules that matter

Record the interest

For each debt item, save the original shortcut, affected paths, every recent symptom, minutes lost, change frequency, and owner. Keep the evidence link beside the estimate.

Set the repayment trigger

Choose a threshold before proposing a rewrite: a third incident, two hours per release, a blocked feature, or an unsupported dependency date. A trigger stops taste from masquerading as priority.

Bound the repair

Compare contain, refactor, replace, and accept. Pick the smallest option that removes the measured interest. Name what will not be cleaned up during this work.

Rules worth keeping beside the code

Record the recurring cost instead of scoring debt by ugliness.
Attach evidence from incidents, delivery delays, and repeated work.
Set a repayment trigger before proposing a rewrite.
Prefer the smallest change that removes the measured cost.

The dangerous version is using debt as a label for disliked code, inventing time savings, starting an unbounded rewrite, or letting old estimates replace current evidence. The pack deliberately stops at a draft so a person can inspect those boundaries before enabling anything real.

Test the ugly paths

Recent examples support the cost estimate.
The trigger is observable.
A named owner reviews the item.
The plan has an acceptance test.
The repayment does not smuggle in an unrelated rewrite.

The final verification is concrete: Sample recent work touching the debt, calculate its observed cost, and confirm the proposed repayment removes that cost with a bounded acceptance test.

Use this prompt to turn the evidence into acceptance tests:

Design tests for Turn Technical Debt Into an Interest Register using only the attached fictional fixtures.
Cover the normal path, missing input, malformed input, a repeated event, a permission failure, a dependency failure, and the named safety boundary.
For each test return: input, expected state, prohibited side effect, and evidence to save.
Do not execute external actions.

Run the pack locally

The ZIP is a complete Node 22 starter with no third-party npm dependency. It includes an importable n8n webhook, Docker Compose, GitHub Actions validation and manual-run workflows, deterministic samples, and tests.

npm test
npm run validate
npm run sample
cp .env.example .env
docker compose up --build

Only set WORKFLOW_MODE=live, ANTHROPIC_API_KEY, and ANTHROPIC_MODEL after the dry-run output and tests make sense for your system. Keep real secrets in the environment, never in the n8n export.

Download the runnable pack

Start with the fictional dry-run. It validates the input and returns a reviewable draft without changing code, production data, customer accounts, or an external service.

Before enabling a real action

Replace every fictional fixture, assign the approval owner, define the duplicate key, set a timeout and retry rule, and save the original evidence. Then test one failure on purpose. If the workflow cannot stop visibly and replay safely, it is not ready to act.