tsa-refactor-queue

tsa-refactor-queue — Top-N prioritized refactor slices

Three signals, one ranked list. Health × churn × dead-code → the five files you'd refactor first if you had a week. Each row carries a target symbol, a blast radius, and a concrete action.

When to use

• "What should we refactor next?" — daily/weekly engineering triage
• Post-feature cleanup pass — find rot that accumulated while shipping
• Pre-sprint planning — turn "we should clean up" into 5 concrete tickets
• After a CI grade-drop alert from tsa-health-watch — re-rank with churn

Don't use when:

• You already know the file (one-file deep dive → health action=file or tsa-edit-safety)
• The codebase is brand-new (<2 weeks of git history) — churn signal is noise
• You want to optimize one hot function — use tsa-graph + edit action=refactor directly
• Shallow clone in CI — git_state=shallow makes mod_count_30d unreliable

Procedure

Step 1 — Single fan-out (parallel, 3 MCP calls)

Call these in ONE message:

1. health action=project with min_grade: "D" and max_files: 20 — F/D files + per-file weakest_dimension
2. health action=dead with max_dead: 200 — symbol-level dead candidates, grouped by file
3. health action=heatmap with top_n: 20 — complexity-weighted file list (covers structural smell)

The three responses overlap on file path. Joining on file_path gives a 3-signal table per candidate.

Step 2 — Score and rank (deterministic, no LLM needed)

For each file that appears in health action=project worst_files, compute:

priority = (1 - health_score/100)            # how bad is the grade
         * log(1 + mod_count_30d_for_file)   # how hot is the file
         * (dead_symbol_count / total_symbols + 0.1)

Where:

• health_score ∈ [0,100] from health action=project (lower → worse → bigger weight)
• mod_count_30d_for_file = sum of mod_count_30d across the file's symbols (read from ast_symbol_activation — see tsa-temporal). log(1+x) damps pathological churn so a single 50× file doesn't dominate.
• dead_symbol_count / total_symbols = fraction of symbols health action=dead flagged. The + 0.1 floor ensures non-dead files can still rank if churn+grade alone justify it.