Assess Technical Debt

Assess Technical Debt

Surface the structural debt that routine review keeps out of scope: long-lived complexity, deprecated APIs, duplication, and tangled architecture that need deliberate refactoring. Project-wide, analysis-only. Ranks each finding by impact and effort and writes .turbo/technical-debt.md and .turbo/technical-debt.html.

Task Tracking

At the start, use TaskCreate to create a task for each phase:

1. Scope and partition
2. Run debt analysis agents
3. Run /evaluate-findings skill
4. Rank and write markdown report
5. Generate HTML report

Step 1: Scope and Partition

If $ARGUMENTS specifies paths, assess those directly (skip the question).

Otherwise, use AskUserQuestion to confirm scope:

• All source files — assess the whole codebase
• Specific paths — user provides directories or file patterns

Once scope is determined:

1. Glob for source files in the selected scope. Exclude generated and vendored directories (node_modules/, dist/, build/, vendor/, __pycache__/, .build/, DerivedData/, target/, .tox/, and others appropriate to the project).
2. Partition files by top-level source directory. If a single directory holds far more files than its siblings, sub-partition it by its immediate subdirectories.

Step 2: Run Debt Analysis Agents

Before dispatching, read the project's test configuration and CI workflow to identify any test tier that resets a shared external resource between tests, such as a database, a fixed port, or a cache. Such tiers have no cross-process interlock, so agents running them concurrently wipe each other's state and return failures that look like real defects. Name any such tier to every agent as off-limits.

Emit all Agent tool calls below in one assistant message. Each Agent call uses model: "opus" and no name. Wait for every agent to report before continuing. Do not begin the next step on a partial set, and do not relaunch an agent that has not yet reported. Each Agent's prompt instructs it to read references/debt-reviewer.md for the debt taxonomy, detection heuristics, the impact/effort rubric, and the finding output format before scanning, and to treat the shared working tree and its git index as read-only — any empirical check runs in an isolated git worktree created under $TMPDIR and discarded afterward. HEAD stays where it is: read other refs with git show <ref>:<path> rather than git checkout or git switch. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. Afterward the agent verifies that git worktree list no longer shows the worktree, that git status --short is clean, that HEAD is still on the branch it started on, and that the shared tree's dependency directory still resolves (a destroyed install leaves git status clean, since it is gitignored). Damage the agent cannot repair is reported with the exact repair command in place of findings.

Expect (one per partition, plus one project-wide architecture agent) Agent tool calls total. State the count explicitly when emitting the calls.

• Partition agents — one per partition from Step 1. Each scans its files for complexity hotspots, deprecated API usage, and duplication, and notes coupling it observes reaching outside the partition. Pass the partition's file list and the full project root path.
• Architecture agent — one project-wide pass over the scoped tree for architecture rot: tangled module boundaries, circular dependencies, layering violations, and refactor candidates that span modules. Pass the partition map and the full project root path.

If more partitions exist than fit a single fan-out, group related directories so the partition agents stay within a manageable batch, and note the grouping in the report.