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 update_plan to track each phase, restating any remaining steps of a parent workflow alongside them:

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 request_user_input 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 sub-agents running them concurrently wipe each other's state and return failures that look like real defects. Name any such tier to every sub-agent as off-limits.

Launch the agents below with spawn_agent / wait_agent using inherited model defaults, issuing every call in one batch. Do not issue one and await its result before issuing the rest. Each sub-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 sub-agent's prompt must also direct it to search the repository with a tool that skips gitignored files, such as git grep --untracked, 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 sub-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 $TMPDIR, 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 sub-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 sub-agent stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the sub-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 sub-agent cannot repair is reported with the exact repair command in place of findings.

Expect (one per partition, plus one project-wide architecture agent) Codex sub-agent calls total. State the count explicitly before emitting the batch.

• Partition agents — one per partition from Step 1. Each scans its files for complexity hotspots, deprecated API usage, duplication, and low-value tests, 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.

Step 3: Run $evaluate-findings Skill

Aggregate all findings from all agents. Deduplicate items that surface in more than one agent (e.g., duplication a partition agent and the architecture agent both flag). Run the $evaluate-findings skill once on the combined set to verify each finding against the actual code and weed out false positives.

Step 4: Resolve Escalated Findings

Skip when Step 3 assigned no Escalate verdict.

For each finding with an Escalate verdict, output its technical detail as text first, including the fact that forces the choice. Then use request_user_input to state the question as the decision the user owns, offering the report outcomes the finding leaves open:

• Rank as debt — the finding enters the priority matrix with its recommended refactor. When the finding carries competing refactors, offer each as its own option.
• Record as intentional — the finding stays out of the priority matrix and is listed with the decision
• Get a second opinion — run the $consult-claude skill for a second opinion on the choice, then ask again with that answer in hand. Offer it when the choice is costly to reverse (it establishes a pattern others will follow, defines an interface, or commits to a data shape), and whenever no option earns (Recommended) with conviction.

Place the strongest option first and append (Recommended) to its label. When the choice hinges on product intent or domain knowledge you lack, say so instead of forcing a pick. Keep the question within three options: when the outcomes exceed that, offer the ones that fit the finding best, with the consultation option among them when it applies, and resolve a freeform answer naming an outcome left out the same way as a selected one.

Step 5: Rank and Write Markdown Report

Assign each surviving finding an impact (maintenance drag, change risk, blast radius) and an effort (rough refactor size) per the rubric in references/debt-reviewer.md. Sort findings into priority tiers:

• Quick wins — high impact, low effort
• Strategic refactors — high impact, high effort
• Incremental — low-to-medium impact, low effort
• Defer — low impact, high effort

Leave a finding recorded as intentional in Step 4 out of the Summary counts and the Priority Matrix, and list it under its dimension in Detailed Findings with that decision. Record the decision beside each escalated finding ranked as debt as well.

Output the summary and priority matrix as text. Then write .turbo/technical-debt.md using the template below.

Report Template

# Technical Debt Assessment

**Date:** <date>
**Scope:** <what was assessed>

## Summary

| Dimension | Findings | High impact |
|---|---|---|
| Complexity hotspots | <N> | <N> |
| Deprecated API usage | <N> | <N> |
| Duplication clusters | <N> | <N> |
| Architecture rot | <N> | <N> |
| Low-value tests | <N> | <N> |

## Priority Matrix

Ranked by impact against refactor effort. Take quick wins first; schedule strategic refactors deliberately.

### Quick Wins (high impact, low effort)
| Item | Dimension | Location | Recommended refactor |
|---|---|---|---|

### Strategic Refactors (high impact, high effort)
| Item | Dimension | Location | Recommended refactor |
|---|---|---|---|

### Incremental (low–medium impact, low effort)
| Item | Dimension | Location | Recommended refactor |
|---|---|---|---|

### Defer (low impact, high effort)
| Item | Dimension | Location | Recommended refactor |
|---|---|---|---|

## Detailed Findings

### Complexity Hotspots
<findings: location, description, impact, effort, recommended refactor, and the recorded decision for an escalated finding>

### Deprecated API Usage
<findings>

### Duplication Clusters
<findings>

### Architecture Rot
<findings>

### Low-Value Tests
<findings>

---
This assessment covers in-code structural debt. For dependency freshness and diff-scoped bugs, run `$review-dependencies` and `$review-code`.

Step 6: Generate HTML Report

Convert the markdown report into a styled, interactive HTML page.

1. Run the $frontend-design skill to load design principles.
2. Read .turbo/technical-debt.md for the full report content.
3. Write a self-contained .turbo/technical-debt.html (single file, no external dependencies beyond Google Fonts) that presents all findings from the markdown report with:

• Summary grid with per-dimension finding counts
• Priority matrix laid out as an impact-by-effort quadrant, color-coded by tier (quick wins highlighted)
• Sticky navigation between sections
• Collapsible dimension sections
• [hidden] { display: none !important; } in the base styles, so a section whose own CSS sets a display value still hides
• Finding cards with location, impact, effort, recommended refactor, and the recorded decision where one exists
• Impact and effort badges with color-coding
• Entrance animations and hover states
• Print-friendly styles via @media print
• Responsive layout for mobile

Then call update_plan to mark this step completed and continue with the next step of the active workflow.

Rules

• Analysis-only: do not modify source code, stage files, or commit.
• If no significant debt is found, report that explicitly and note any scope limitations or analysis caveats.