---
name: tech-debt-audit
description: Whole-repo technical debt audit with file-cited findings and ranked remediation plan.
---

## orient
role: explorer
output: audit-orientation.md

Map the repository for a technical debt audit. Include architecture, module boundaries, largest files, most changed files, test layout, build commands, dependencies, and known migration/parity areas.

Tool policy: do not call `glob` or any unavailable abstract discovery tool. Use bash discovery only: `rg --files`, `rg -n`, `find`, `sed`, `nl`, and `git grep`. If a tool returns `Tool <name> not found`, stop using it immediately; if the same tool error repeats twice, stop the task and report the blocker. Do not repeat failed tool calls or shell commands. If a command exits non-zero with no useful output, do not retry it unchanged; inspect source/tests or change the hypothesis first. If a focused test fails, use the failure location to inspect and fix code/tests; do not repeatedly grep test output for unrelated terms. After two failed verification attempts without a code or test change, stop and report the blocker. Do not continue after five consecutive calls that add no new information.

## audit
role: tech-debt
dependsOn: orient
reads: audit-orientation.md
output: TECH_DEBT_AUDIT.md

Run a whole-repo technical debt audit for: {goal}

Produce file:line-cited findings, severity, effort, top priorities, quick wins, "looks bad but is actually fine", and open questions. Do not edit production code.

## critique
role: critic
dependsOn: audit
reads: TECH_DEBT_AUDIT.md
verify: true

Challenge the audit for shallow findings, missing evidence, generic advice, false positives, and missing migration/parity debt.

## finalize
role: docs
dependsOn: critique
reads: TECH_DEBT_AUDIT.md
output: audit-summary.md

Summarize the audit status, next actions, and whether `TECH_DEBT_AUDIT.md` is ready to commit.