debt-collector

name	debt-collector
description	Audit a codebase for removable technical debt and, when asked to act on findings, implement targeted removals safely. Use when the user asks to collect technical debt, find deletion candidates, remove dead code, act on findings, apply debt findings, start work on debt, audit stale endpoints/jobs/tests, or look for code smells, dead tests, deprecated paths, unused code, or expensive stale systems.

Debt Collector

Use this skill to find high-confidence debt removals first, then remove them carefully when the user asks for action.

Modes

Start in audit mode unless the user asks to "act on findings", "apply them", "start work", "remove", "kill", or otherwise requests implementation.

In audit mode:

1. Read project instructions and current worktree state.
2. Load available helper skills before the audit:
   • be-thorough for breadth, adversarial checks, and evidence quality.
   • audit-code for code review and smell detection.
   • Any project-specific debugging, production-ops, logs, observability, or domain skill that can verify runtime assumptions.
3. Note every expected helper skill that is missing. Include a URL for each missing skill in the final report. If no canonical URL is known, use a GitHub search URL for the exact skill name.
4. Search for debt categories:
   • Dead code and unused exports.
   • Dead, duplicated, skipped, or obsolete tests.
   • Code paths that appear uncalled or only used by stale compatibility layers.
   • Deprecated feature flags, env vars, API routes, jobs, migrations, cron entries, workflow definitions, and temporary rollouts.
   • Code smells with measurable removal value: needless abstractions, old adapters, broad catch-all handlers, expensive polling, duplicated logic, abandoned tooling, and unreachable branches.
5. Check assumptions with runtime evidence when possible. Use logs, metrics, traces, traffic, usage tables, CI history, package graphs, or project-specific debugging tools. Treat "not found by grep" as a hypothesis, not proof.
6. For each promising candidate, gather provenance before ranking it:
   • Who added it and who last materially changed it, if those differ.
   • When it was added and when it was last materially changed.
   • Commit hash and commit subject for each meaningful commit.
   • PR number/title/description summary or review context when available.
   • Any stated reason from the commit message, PR text, code comment, migration note, or docs. If provenance cannot be established quickly, say that explicitly; do not omit the field.
7. Before calling anything junk, test the strongest alternate explanations. For example, an "example package" might be a scaffold template, a fixture, a teaching sample, a package-boundary test, or a generated-code sentinel. Check docs, generators, package manifests, tests, scripts, and dynamic/string references before recommending deletion.
8. Stop once you have five strong candidates, unless the codebase is small enough to finish the pass quickly. If you already have a task list from an earlier run, start there and revalidate before adding new candidates.
9. Rank candidates by default preference: lowest removal risk, highest compute or operational gain, then highest line-count reduction.

In implementation mode:

1. Revalidate the selected finding before editing.
2. Use be-thorough, audit-code, clauditor, and project-specific debugging skills if available. Be self-adversarial: look for hidden call sites, generated-code contracts, public API compatibility, deployment assumptions, migration history, and test fixtures.
3. Make one targeted patch per finding, in ranked order. Keep each patch narrow enough to reason about independently.
4. Add or update tests only where they prove behavior or deletion safety. Prefer focused regression tests over broad snapshots.
5. Validate with the project's normal commands. If project instructions require a PR, submit one using the project's workflow; otherwise leave changes local and report exact files and checks.
6. Before finalizing, run a final adversarial pass. Use thermo-nuclear-code-quality-review and a second audit-code pass if available.

For scoring details and report format, read references/debt_protocol.md.

Evidence Standard

Prefer concrete evidence over vibes:

• Static evidence: call graphs, imports, exports, package manifests, route registration, test selectors, generated schemas, dead-code tooling.
• Runtime evidence: logs, metrics, traces, traffic, recent production calls, queue/workflow history, customer-visible usage, CI/job history.
• Historical evidence: deprecation comments, old migration dates, stale feature flags, release notes, previous task lists, PR history.

When evidence conflicts, report the conflict and keep the candidate out of the top five unless the removal can be staged safely.

Final Reports

For audit mode, report the top five candidates with:

• Candidate name and location.
• Plain-English explanation of what the code is and why someone should care. Assume the reader has not touched that subsystem.
• Origin story: who added it, who last materially changed it, when, commit hashes/subjects, PR numbers/titles/description summaries if available, and the best available stated justification.
• The issue, stated directly in one or two sentences. Make it unmissable what is wrong.
• Evidence gathered and evidence still missing.
• Alternate-use check: explain whether it might be a template, fixture, public compatibility layer, generated artifact, replay/migration shim, customer contract, or deployment hook. State what you checked and what remains unknown.
• Risk level and blast radius.
• Expected benefit: compute/ops gain, line-count reduction, complexity reduction, or test/runtime simplification.
• Recommended first patch.
• Verdict: delete now, stage first, needs runtime proof, or do not delete yet.

For implementation mode, report:

• Findings acted on and why.
• Files changed.
• Validation run and results.
• Remaining risks or follow-up candidates.
• Helper skills used and helper skills missing, with URLs for missing skills.