Tech Debt Map

Produce a debt map: a ranked, evidence-backed list of what is worst about this codebase right now, and a plan to fix it a slice at a time.

The map is a diagnosis, not a refactor. Nothing in the codebase changes during this skill. What you hand back is a file the user can work through over weeks, and re-run against later to see what moved.

Two neighbours to stay out of the way of: /improve-codebase-architecture hunts one class of problem (shallow modules) and ends in a grilling session about a single candidate; /review-axes judges a diff. This one sweeps the whole project, across every axis, and ends in a written map.

Process

1. Scope

Auditing everything means auditing nothing well, so decide where to look before you look.

• If the user named a direction (a module, a subsystem, a pain point), take it.
• Otherwise find the hot spots: git log --oneline --since='6 months ago' --name-only and count which paths keep coming up. Churn is where debt actually costs money, so let those paths pull your attention first. Widen the net when churn is evenly spread.
• Read CONTEXT.md (domain vocabulary), any ADRs, and CLAUDE.md/AGENTS.md (the standards the repo already committed to). A decision recorded in an ADR is settled, not a finding.
• Leave out what the team does not own: vendored code, generated files, lockfiles, build output, migrations already applied.