Debt Runner

Interactive orchestrator for the Technical Debt Management System. Sequences existing TDMS scripts, applies convergence-loop verification at every stage, and owns the remediation plan artifact.

Critical Rules (MUST follow)

1. Never write MASTER_DEBT.jsonl directly — all mutations go to staging files in docs/technical-debt/staging/. CL verifies staging, then existing scripts (intake-audit.js, resolve-bulk.js, etc.) apply to canonical files.
2. Convergence-loop on every mode — no mode completes without CL verification. Presets vary by mode (see each mode section).
3. Post-mutation sync check — after any pipeline that modifies MASTER_DEBT, run CL quick preset verifying MASTER_DEBT.jsonl and raw/deduped.jsonl item counts match + spot-check recent mutations in both files.
4. Confirmation gate at >100 mutations — present count + 10-item preview. User approves before applying.
5. Return to menu after each mode — present updated stats + mode menu. User picks next mode or exits.

When to Use

• Verifying accuracy of current technical debt items
• Syncing new debt from SonarCloud or other sources
• Planning and prioritizing debt resolution
• Running deduplication, validation, or cleanup pipelines
• User invokes /debt-runner or any mode variant

When NOT to Use

• Adding a single debt item manually — use /add-debt
• Full SonarCloud interactive experience — use /sonarcloud --interactive
• Auditing the TDMS ecosystem health — use /tdms-ecosystem-audit
• Reviewing debt in context of a PR — use /pr-review

Routing Guide

Input

Invocation: /debt-runner [mode] [--severity S0,S1] [--interactive]

Modes: verify, sync, plan, health, dedup, validate, cleanup

No args → interactive menu with live stats.

Process Overview

WARM-UP    → Stats, effort estimates, resume check
MENU       → Show stats, present 7 modes, user selects
MODE       → Execute selected mode with CL verification
SYNC-CHECK → Post-mutation MASTER_DEBT ↔ deduped.jsonl CL verify
RETURN     → Back to menu with updated stats, user picks next or exits

Resume entry: If state file exists with incomplete mode, present: "Resuming debt-runner. Last mode: [mode], step [N]. Continue? [Y/restart]"

Warm-Up (MUST)

Present before the menu:

• Current debt stats (S0-S3 counts)
• Effort estimates per mode: verify (~10min S0, ~30min all), sync (~5min + CL), plan (~15min), health (~5min), dedup (~20min), validate (~10min), cleanup (~10min)
• Resume status if applicable
• Pending staging files if any

Done when: User acknowledges, proceeds to menu.

Interactive Menu (MUST for no-args invocation)

Read REFERENCE.md for the menu rendering template and stats source commands.

Debt Runner — Interactive Mode
S0: [N] | S1: [N] | S2: [N] | S3: [N] | Total: [N]
Last sync: [date] | Last verify: [date] | Pending staging: [N files]

1. verify   — Verify current debt accuracy via convergence loop
2. sync     — Run SonarCloud sync + intake pipeline
3. plan     — Create resolution plan for target severities
4. health   — Surface debt metrics, trends, staleness
5. dedup    — Run deduplication with CL-verified merge decisions
6. validate — Schema validation + stale item detection
7. cleanup  — Archive resolved, clear FPs, regenerate views

Select mode [1-7]:

Stats: Run node scripts/debt/generate-metrics.js, check docs/technical-debt/staging/ for pending files.

Mode: Verify (CL standard/thorough)

Verify current debt items accurately reflect codebase reality.

1. Load items filtered by --severity (default: all)
2. CL preset by severity — see REFERENCE.md slicing templates. S0 gets thorough attention within the standard pass structure. Each agent checks: does file exist? Is the issue still present? Fixed but not marked resolved?
3. Present T20 tally after each pass. User gate per pass.
4. Write corrections to staging/verify-corrections.jsonl
5. Apply via node scripts/debt/resolve-bulk.js for items to resolve
6. Post-mutation sync check (Critical Rule #3)

Done when: CL converged, corrections applied, sync check passed.

Mode: Sync (CL standard)

Sync new debt from SonarCloud and run intake pipeline.

1. Run node scripts/debt/sync-sonarcloud.js --dry-run — preview
2. Present preview: N new items, severity breakdown. User confirms.
3. Run node scripts/debt/sync-sonarcloud.js --force
4. CL standard preset — slice by source batch. Verify severity classifications, dedup accuracy, file paths and line numbers.
5. Write corrections to staging/sync-corrections.jsonl
6. Apply corrections, post-mutation sync check

Done when: Sync complete, CL verified, sync check passed.

Mode: Plan (CL standard)

Read REFERENCE.md for remediation plan JSONL schema.

Create a prioritized resolution plan for target severities.

1. Filter MASTER_DEBT by --severity (default: S0,S1)
2. Analyze: group by file, category, effort. Identify dependencies.
3. Generate resolution order: S0 first, then by effort (E0→E3), cluster by file
4. Write docs/technical-debt/plans/resolution-YYYY-MM-DD.jsonl + .md view
5. CL standard preset — verify plan claims: file paths exist, items not already resolved, effort estimates reasonable, dependencies captured
6. Present plan to user for approval
7. Handoff: manual for <10 items, subagent for 10+. Flag S0 security for /security-auditor.

Done when: Plan generated, CL verified, user approved.

Mode: Health (CL quick)

Surface debt metrics, trends, and staleness indicators.

1. Run node scripts/debt/generate-metrics.js
2. Run node scripts/health/checkers/debt-health.js
3. CL quick preset — verify: item counts match MASTER_DEBT line count, severity distribution matches, stale items (>90 days) correctly identified
4. Present dashboard: severity breakdown, trend, stale count, top categories

Done when: Metrics presented, CL verified.

Mode: Dedup (CL standard)

Run deduplication with verified merge decisions.

1. Run node scripts/debt/dedup-multi-pass.js --dry-run — preview merges
2. Write proposed merges to staging/dedup-merges.jsonl
3. CL standard preset — slice by merge-candidate clusters. Verify candidates are truly duplicates, merge target retains best info, no S0/S1 absorbed into lower severity
4. Present merge decisions (batch if >20, delegation available)
5. Apply: node scripts/debt/dedup-multi-pass.js --force
6. Run node scripts/debt/consolidate-all.js
7. Post-mutation sync check

Done when: Dedup complete, CL verified, sync check passed.

Mode: Validate (CL standard)

Schema validation + stale item detection.

1. Run node scripts/debt/validate-schema.js
2. Run node scripts/debt/verify-resolutions.js
3. CL standard preset — verify: schema violations are real (not schema evolution FPs), stale items genuinely stale, resolution claims match code
4. Present findings with fix recommendations
5. Write fixes to staging/validate-fixes.jsonl
6. Apply fixes, post-mutation sync check

Done when: Validation complete, CL verified, fixes applied.

Mode: Cleanup (CL standard)

Archive resolved items, clear false positives, regenerate views.

1. Identify resolved items >30 days old + confirmed false positives
2. CL standard preset — verify: resolved items genuinely resolved (spot-check code), false positives genuinely false
3. Present cleanup plan: N to archive, M FPs to clear. User confirms.
4. Apply via existing scripts
5. Run: sync-deduped.js → generate-views.js → generate-metrics.js
6. Post-mutation sync check

Done when: Cleanup applied, views regenerated, sync check passed.

Post-Mutation Sync Check (MUST after any mutation mode)

1. CL quick preset on MASTER_DEBT ↔ raw/deduped.jsonl:
   • Item counts match
   • 10 random recent mutations appear in both files
   • No orphaned items in either file
2. If divergent: run node scripts/debt/sync-deduped.js and re-verify
3. If still divergent: warn user, do NOT proceed to next mode

Guard Rails

• >100 mutations: Confirm + 10-item preview before applying
• Staging safety: Never deleted until full pipeline succeeds. On successful mode completion, delete that mode's staging files. On session exit, warn if staging files remain from incomplete modes.
• Error recovery: Save state with failed step. /debt-runner resume
• MASTER_DEBT protection: All writes via existing dual-write scripts
• S0 security: Recommend /security-auditor before resolution
• Empty-result short-circuit: If a mode produces zero items to process, skip CL verification and report "No items found. Returning to menu."
• Delegation protocol (>20 items): For any mode presenting >20 items for decision, offer: "You decide" (apply all recommendations), severity filter ("skip remaining S3"), or batch review. Applies to all modes uniformly.

Compaction Resilience

• State file: .claude/state/debt-runner.state.json
• Update: After each mode completion and each CL pass
• Staging files: On disk in docs/technical-debt/staging/, survive compaction
• Resume: /debt-runner resume reads state, skips completed steps

Integration

• Neighbors: /sonarcloud (sync scripts), /add-debt (intake), /convergence-loop (all modes), /tdms-ecosystem-audit (ecosystem health)
• Downstream: Execution after plan, /security-auditor for S0 security, /code-reviewer for affected files
• Auto-triggers: generate-views.js + generate-metrics.js after cleanup
• Script progress (MUST): Before each script call, print "Running [script]..." After completion, print result summary. Prevents user uncertainty during long operations.
• Retro prompt (SHOULD): On session exit (not per-mode), prompt: "Any modes that produced unexpected results? Any scripts that need attention?" Capture in state file process_feedback.

Version History