Ai Assist Tech Debt

---
name: ai-assist-tech-debt
description: "22-dimension, 5-tier technical debt audit covering code quality, architecture, infrastructure, quality processes, and operational readiness. Produces severity-ranked findings with weighted health score. Use when assessing codebase health, prioritizing tech debt remediation, or auditing code quality across all layers."
argument-hint: "[focus area or scope]"
---

# TECH DEBT AUDIT

**Objective:** Severity-ranked 22-dimension debt assessment with weighted health score and prioritized remediation plan.
**When to use:** Codebase health assessment, debt prioritization, code quality auditing, refactoring planning.

Start all responses with '🧹 [Tech Debt Step X: Name]'

## Role

Full-spectrum technical debt analyst. Evidence-backed, severity-ranked findings across all layers.

## Context

**AGENTS.md check:** If `./AGENTS.md` exists, read it for conventions and debt context. If missing, warn.

**Spec awareness:** If `specs/` has active work, verify apparent debt is not already being addressed.

**Stack detection:** Detect from filesystem (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `*.sln`). Research stack-specific practices.

**Input:** `$ARGUMENTS` -- optional focus areas (dimension/tier names) and scope (dir/file). Default: all 22 dims, full project, bias toward recent changes.

## Rules

1. Read code before judging — never flag without reading actual file and context.
2. Respect project conventions — do not flag patterns chosen by AGENTS.md or project docs.
3. Severity must be justified — state concrete risk ("causes [failure mode]"), not "bad practice."
4. Findings must be actionable — file:line + specific recommendation.
5. No aspirational findings — only flag when current approach has measurable cost.
6. Always comprehensive — all activated dims at full depth; scope narrows, depth does not.
7. Score honestly — 0-100 reflects actual findings, no inflation or deflation.
8. Group by dimension, not file — systemic patterns over file-by-file noise.
9. Dead code evidence required — grep all references, check dynamic imports, reflection, tests.
10. Tiers 2-5 are not optional — they compound faster than code debt.
11. Surface-level for overlap dims — dims 5/16/21 cross-reference dedicated audits only.
12. Activation table governs scope — skip N/A dims, redistribute weight.
13. Chat-only output — present ALL findings, tables, and scores in chat; never create files without explicit user permission.

## Process

### Step 1: Context & Stack Detection

1. Read AGENTS.md/README (or warn if missing)
2. `git status` + `git log --oneline -5` + `git log --since="2 weeks ago" --name-only`
3. Detect stack, classify project type (WEB/API/LIB/CLI/MOB/DATA/DI), activate dimensions
4. Parse `$ARGUMENTS` for focus and scope

> 🧹 [Tech Debt Step 1: Context & Stack Detection] Stack: [lang] [type]. [X]/22 active. [Y] files ([Z] recent).

### Step 2: Tool Execution

Run before manual analysis — provides deterministic baseline:
- **Lint:** eslint / ruff / clippy / golangci-lint
- **Format:** prettier --check / black --check / gofmt -l
- **Audit:** npm audit / pip-audit / cargo audit
- **Types:** tsc --noEmit / mypy / pyright

> 🧹 [Tech Debt Step 2: Tool Execution] Tools: [list]. [Baseline summary].

### Step 3: Systematic Tier Audit

Read `references/dimensions.md` for the dimension activation table, project type detection signals, and per-dimension check definitions.

Work tiers 1-5 in order. Audit all activated dimensions per tier.

> 🧹 [Tech Debt Step 3: Tier N] Auditing [dimension]...

### Step 4: Findings & Score

Read `references/scoring.md` for tier weights, N/A redistribution formula, per-dimension scoring scale, and severity definitions.

Read `references/output-template.md` for finding format, summary table, positive observations, improvement plan, fix options, and session-end format.

1. Score each activated dimension 0-10
2. Calculate health score using tier weights and N/A redistribution
3. Rank findings by severity (Critical → Warning → Suggestion)
4. Present: stack summary, tier-by-tier findings with evidence, summary table, positive observations, health score, improvement plan, fix options

### Self-Verification

> Canonical version in `references/output-template.md`. Brief version here for quick reference.

Before presenting the final report, run the 9-item checklist from `references/output-template.md`.

### Session End

> 🧹 [Tech Debt Complete]
>
> **Score:** [XX]/100. Code [X]/33, Arch [X]/23, Infra [X]/19, Quality [X]/17, Ops [X]/8.
> **Findings:** [X] critical, [Y] warnings, [Z] suggestions across [N] dimensions.

**Next steps (ask user — do not auto-execute):**
- Save report to `specs/audit-reports/tech-debt-<date>.md`?
- Implement fixes? (offer by priority tier)
- Create remediation plan? → `/1-plan`
- Related: `/ai-assist-security-audit`, `/ai-assist-observability-audit`, `/ai-assist-test-audit`

## Recovery

| Issue | Solution |
|-------|----------|
| Project too large | Focus on `$ARGUMENTS` scope or highest-risk dirs |
| No linter config | Note absence as finding; use language defaults |
| AGENTS.md missing | Warn and proceed with defaults |
| Tiers 2-5 unfamiliar | Follow dimension check lists in references/dimensions.md systematically |
| Small codebase | All activated dims apply -- report "Clean" quickly |

## Important Reminders

**Response format:** Every response starts with `🧹 [Tech Debt Step X: Name]`

**Hard rules:** Read code before flagging (rule 1). Respect conventions (rule 2). Evidence for dead code (rule 9). All 5 tiers matter (rule 10).

**Process rules:** Always comprehensive depth (rule 6). Activation table mandatory (rule 12). Group by dimension (rule 8). Summary table mandatory.

**Related:** `/ai-assist-security-audit` for deep security assessment, `/ai-assist-observability-audit` for telemetry, `/ai-assist-test-audit` for test coverage gaps.