arthai-marketplace

/tech-debt

Holistic tech-debt audit — DRY violations, dead code, design smells, coupling, deprecated patterns. File-cited findings with severity tiers.

Synopsis

/tech-debt [scope] [--audit-only] [--workflow|--classic] [--invoked-by VALUE]

When to use it

Quickstart

/tech-debt

What you’ll see: a quick structural scan, then three parallel auditors covering DRY/dead code, smells/coupling, and deprecated patterns — each auditor works its own slice of the codebase independently (“isolated”), so they don’t wait on each other or duplicate context, which is what makes the workflow path faster on large repos. The result is a report with Critical / Important / Suggestion findings (each cited as file:line), a per-dimension summary table, and a baseline saved for future delta comparison.

Examples

/tech-debt                       # full codebase audit
/tech-debt backend/services/     # audit one module
/tech-debt auth                  # audit a feature area
/tech-debt --audit-only          # report only, no follow-up prompts (good for automation)
/tech-debt --classic             # force the legacy parallel-agent path instead of the workflow path

Arguments & flags

Flag Values Default What it does
scope file, directory, feature, all all What to audit
--audit-only — off Skip interactive prompts; just present the report
--workflow / --classic — auto by repo size Force the execution path; workflow fans out isolated auditors in parallel (~3-4x faster on large repos). Auto rule: <200 files → classic, ≥500 files → workflow, 200-500 files → workflow if scope is all, else classic. Workflow path requires Claude Code ≥ 2.1.154; falls back to classic with a prompt to run claude update if the version is too old
--invoked-by direct, calibrate_rescan, autopilot, pr, implement, onboard direct Caller identity for telemetry — set automatically by cross-skill hooks

What it does

  1. Loads context — CLAUDE.md, project profile, your coding conventions and patterns (to detect violations against them), the prior baseline, and .claude/tech-debt-config.json (severity caps, ignore paths) if present.
  2. Quick scan — explore-light maps hotspots: duplicate blocks, oversized files, TODO/FIXME density, coupling hubs, dead files, and untested source files.
  3. Picks the execution path — workflow (parallel isolated auditors, chosen automatically for large repos) or classic; may prompt once to enable workflows if your Claude Code settings have them disabled — user-confirmation checkpoint in that case. The workflow path requires Claude Code ≥ 2.1.154 — if your version is older, you’ll see a one-time prompt to run claude update, and the audit falls back to the classic path automatically (no data is lost, just less parallelism).
  4. Deep audit — three auditors run in parallel: DRY violations + dead code; code smells + design-pattern decay (deviations from your codebase’s own patterns, not generic preferences); deprecated patterns (flagged only when the same repo already does it the modern way). No code is modified.
  5. Dedupes and prioritizes — drops findings already tracked in QA incidents, applies severity caps, and computes the delta against the prior baseline ([NEW] / [RESOLVED] tags).
  6. Writes the baseline — human-readable and machine-readable baseline files for trend tracking; other skills (/pr, /implement, /review-pr) reference it automatically.
  7. Presents the report and offers next steps (plan the fixes, file issues, or stop). The prompt is skipped with --audit-only or when invoked by another skill.

Configuration

Optional file: .claude/tech-debt-config.json. If it doesn’t exist, defaults apply (severity caps: critical 25 / important 50 / suggestion unlimited; no ignored paths).

{
  "severity_caps": {
    "critical": 25,
    "important": 50,
    "suggestion": null
  },
  "triggers": {
    "pr": "enabled",
    "implement": "enabled",
    "onboard": "enabled",
    "autopilot": "enabled",
    "calibrate_rescan": "enabled"
  },
  "ignore_paths": [],
  "ignore_patterns": []
}
Field What it does
severity_caps Max findings shown per tier before the report truncates and notes how many were omitted. null/absent = unlimited. Defaults: critical 25, important 50, suggestion unlimited
triggers Per-caller mute switches — set a caller (e.g. "pr": "disabled") to skip auto-invocation from that cross-skill hook. All default to enabled if the key is absent
ignore_paths Paths excluded from the audit entirely
ignore_patterns Specific code patterns to treat as known false positives, so they stop reappearing in every run

Agents spawned

Agent Model tier Role
explore-light haiku Structural hotspot scan + deprecated-pattern audit
code-reviewer ×2 sonnet DRY/dead-code auditor and smells/coupling auditor
completion-verifier sonnet Verifies the audit completed what it claimed

Output & artifacts

Troubleshooting

Problem Fix
Too many findings to act on Set severity_caps in .claude/tech-debt-config.json to cap critical/important counts (defaults: critical 25, important 50, suggestions unlimited if no config file exists)
Known false positives keep appearing Add them to ignore_paths / ignore_patterns in the config file
Dynamic workflows need Claude Code ≥ 2.1.154 Run claude update, or pass --classic — the audit runs either way
Findings duplicate things you already track Findings matching existing QA incidents are tagged [ALREADY TRACKED] and excluded from counts automatically