debt-audit

Debt Audit

Run every debt dimension and find the places where debt compounds.

Philosophy

"Where does our debt concentrate, and what's the single highest-leverage place to repay?"

Running each dimension separately is fine, but patterns emerge only when you look across them. A module flagged by code-debt, test-debt, AND design-debt isn't three separate problems — it's one neglected area. The umbrella's job is surfacing that.

Scope

User may specify a path, glob, or directory. Whole-project scans are valid but can be long. If not specified, ask: "Which directory should the audit cover? (Project root is fine for small codebases; a subsystem for larger ones.)"

Config Integration

Follow references/config-migration.md for preflight.

Read .assistant-config.md for:

• Debt Scope — any dimensions permanently out of scope
• Acknowledged Debt

Dimension Selection

Before running, show the user the five dimensions and allow per-run exclusion via AskUserQuestion:

Will check: code, doc, test, dep, design. Exclude any for this run? (none / list)

Respect .assistant-config.md Debt Scope exclusions as defaults.

Process

1. Run each dimension

For each selected dimension, invoke the dimension skill via the Skill tool, passing the same scope:

• code-debt <scope>
• doc-debt <scope>
• test-debt <scope>
• dep-debt <scope>
• design-debt <scope>

Capture each sub-report as text.

2. Parse sub-reports

For each report, extract (per the parsing contract in references/debt-output-format.md):

• Dimension name
• Every file:line entry under ### Findings
• The single Impact/Effort/Priority triple per location group
• Each Ready-to-file item as a complete block

Build a location map:

{
  "src/auth/handlers.ts": {
    "code": [...findings],
    "test": [...findings],
    "design": [...findings]
  },
  "src/orders/": {
    "dep": [...findings]
  }
}

3. Score hotspots

• Systemic hotspot: any location appearing in three or more dimensions.
• Deep debt zone: any location with five or more findings in one dimension.