assess-technical-debt

Assess Technical Debt

Surface the structural debt that routine review keeps out of scope: long-lived complexity, deprecated APIs, duplication, tangled architecture, and low-value tests 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. Resolve escalated findings
5. Rank and write markdown report
6. Generate HTML report

Step 1: Scope and Partition

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

Otherwise, use AskUserQuestion to confirm scope:

• Whole codebase — assess all source and test files
• Specific paths — user provides directories or file patterns

Once scope is determined:

1. Glob for source and test 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 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. Every agent's prompt must direct it to omit name on any Agent tool call it makes itself. 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. Every agent's prompt must also direct it to search the repository with a tool that skips gitignored files, such as git grep --untracked or the Grep tool, and to open or search a gitignored path only when its prompt or a file its prompt directs it to read names it, or when a dependency's installed source is needed to verify a claim, never one holding local configuration or credentials. Each agent keeps the scratch files it writes, such as its starting git status snapshot, probes, and logs, in a scratch directory of its own, uniquely named under the session scratchpad directory, and refers to it by absolute path. HEAD stays where it is: read other refs with git show <ref>:<path> rather than git checkout or git switch. Refer to that worktree by absolute path in every command and join chained steps with &&, so a failed step cannot leave the rest running in the shared checkout. Run teardown and verification as their own commands. 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. Every test runner the agent starts, in a worktree or in the shared checkout, runs in its own process group under a timeout enforced from outside the runner. Before teardown, the agent stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the agent verifies that git worktree list no longer shows the worktree, that git status --short shows what it showed at the start, 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 unchanged, since it is gitignored). It also confirms that no process from those groups, and none whose command line names the worktree path, if any, is still running, and reports by PID any process it could not stop. When it cannot list processes, it reports that check as unrun and names those process groups and the worktree path, if any. Damage the agent cannot repair is reported with the exact repair command in place of findings.