tech-debt-audit

Tech Debt Audit

Produce a verified, ranked debt register a team can turn into work items. Keep the audit read-only: do not edit, format, commit, push, install, upgrade, run migrations, or send repository data to external services.

Definition

Technical debt is a set of design or implementation constructs that are expedient in the short term but make future changes more costly or impossible. Its impact is limited to internal qualities, mainly maintainability and evolvability.

• Principal is the effort to remove the debt. Interest is the extra cost the debt adds to each change that touches it: slower delivery, more defects, more risk.
• Debt in code that rarely changes charges little interest. Rank messy code that changes often above ugly code that is stable.
• A defect that produces wrong behavior today is a bug, not debt. So is an exploitable security issue. A missing feature, a style preference, or "not the latest trend" is not debt unless you can show a cost.
• Record the origin as deliberate only when a comment, ADR, commit message, or issue shows it. Otherwise use inadvertent or unknown.

Budget

• Launch at most four subagents, in one wave. Do not relaunch them, chain them, or let them spawn subagents. Use the yarstack:reviewer agent for each lane when the host provides it. For a repository under about 20k lines or with a single module, use at most two, and do the remaining lanes yourself.
• Use subagents only when the host supports them and the user permits it. Otherwise run the lanes in sequence and label the result as degraded.
• Use a lower-cost model at low or moderate effort for lanes. Keep deduplication, verification, and ranking with the lead.
• Cap each lane at about 40 file reads and 15 findings. When a lane reaches the cap, it stops and reports what it did not cover.

Build the shared inventory

The lead does this once, and every lane receives the result. Lanes must not repeat any step.

1. Confirm the target, excluded paths, and output location. Read repository instructions, README, contributing guides, ADRs, and architecture docs. Skip vendored, generated, and build output except for dependency analysis.
2. Record languages, modules with one-line purposes, entry points, and the build, test, lint, and CI commands. Run only trusted read-only commands.
3. Find the top 30 files by commit count over the last 12 months, or over the full history if it is shorter: git log --since="12 months ago" --name-only --format= | sort | uniq -c | sort -rn.
4. Mark as hotspots the 10–15 files with both high churn and high complexity. Measure complexity with size and nesting depth, or with a complexity tool that is already installed.
5. List co-change pairs that cross module boundaries, and single-author hotspots from git shortlog.
6. Count TODO, FIXME, HACK, XXX, @deprecated, and lint or type suppressions per directory, and keep the 20 most informative lines.
7. Note which lint rules are disabled, which coverage reports exist, and which dependency manifests exist.