Tech debt report

Get a ranked tech-debt report for a codebase: read-only agents each look through one lens, then one agent merges their findings into a single list ordered by cost and risk.

One agent per lens

From a terminal in the repo's workspace:

beswarm agent start --name todos --agent claude --group debt --no-focus \
  --prompt "Read-only. Find TODO, FIXME and HACK comments. Use git blame for their age. List them oldest first with file, line and what they defer. Write to reports/debt/todos.md."
beswarm agent start --name dead --agent codex --group debt --no-focus \
  --prompt "Read-only. Find dead code: unused exports, unreachable branches, files nothing imports, flags that are always on or off. Write to reports/debt/dead-code.md with file and evidence for each."
beswarm agent start --name deps --agent gemini --group debt --no-focus \
  --prompt "Read-only. List dependencies more than one major version behind or unmaintained for over a year. For each, give current and latest version and how much code touches it. Write to reports/debt/deps.md."
beswarm agent start --name hotspots --agent claude --group debt --no-focus \
  --prompt "Read-only. Using git log for the last 6 months, find the files that change most often. For the top 15, judge size, complexity and test coverage. Write to reports/debt/hotspots.md."

Hotspots matter most: a messy file nobody touches costs nothing, a messy file changed every week costs you every week.

Rank it

for a in todos dead deps hotspots; do
  beswarm agent wait "$a" --until done,blocked --timeout 2400
done
 
beswarm agent start --name debt-rank --agent claude --group debt \
  --prompt "Merge everything in reports/debt/ into reports/debt/summary.md: one table ranked by (cost of leaving it) × (risk of fixing it), with an effort estimate of S, M or L. Then the top five to tackle next quarter, each with a one-paragraph case. Cite the source report for every item." \
  --wait --timeout 1200

Act on it

Take the top items to your planning meeting. When one is approved, hand it to an agent in its own worktree, as in Migration sweep.

Run the same group again next quarter and diff the two summaries to see whether debt is going up or down.