---
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. Treat semantically equivalent commands as repeats even when numeric limits or filters change; do not widen `sed`, `head`, `tail`, or `git diff | grep` ranges step by step.

## 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.