Hotspot optimizer
Find and (on request) fix complexity/performance hotspots with behavior preserved and proven by
tests. Bias toward small, verified wins over broad rewrites.
Core rule
Never change observable behavior. Every optimization preserves outputs, ordering, error semantics,
and public APIs — and is proven by a test that passed before and after.
Loop: Triage → Prove → Optimize → Verify
- Triage — get candidate leads fast, then reason about them:
- First pass (cheap, optional):
python3 scripts/scan_hotspots.py <root> --format json for a
ranked multi-language lead list. Treat output as leads, not proof.
- Confirm with
Grep/Glob/Read: nested loops over the same data, membership tests in a loop
(list vs set), sort-in-loop, pairwise comparisons, repeated scans, render recomputation, N+1
queries. Rank by impact (hot path × input size), not raw count.
- Prove — before touching hot code, run/author a focused test that pins current behavior and, if
feasible, a quick timing or complexity witness.
- Optimize — apply the smallest localized
Edit that lowers complexity (see
references/optimization-playbook.md). No drive-by refactors or formatting churn.
- Verify — re-run the focused test, then the broad gates (type-check, lint, build, suite). If any
regresses, revert that change.
Subagent fan-out
For large repos, shard files/dirs across Task subagents (read-only). Each returns a ranked findings
list: file:line, pattern, estimated current → target complexity, risk. The main agent dedupes and
merges into one ranked plan, then optimizes serially (it owns all edits). Cap concurrency at ~4-6
subagents; prefer fewer, broader shards over many tiny ones.
Optimization safety checklist
- Same outputs for the same inputs (including ordering and ties).
- No swallowed/altered exceptions; same error types.
- No new unbounded memory (a set/dict cache must be bounded by the same data).
- Equivalent for empty / single / duplicate / large inputs.
- Public API and call sites unchanged.
Analysis-only by default
Default to a report (see references/report-template.md): ranked findings with location, current and
target complexity, risk, and a proposed fix — but do not edit. Apply fixes only when the user says
implement / fix / apply / refactor (or pre-approves low-risk wins like list→set membership).
Resources
scripts/scan_hotspots.py — heuristic multi-language hotspot scanner (leads only).references/optimization-playbook.md — transformation catalog + correctness checks + what-not-to-do.references/report-template.md — analysis-only report skeleton.
1---2name: hotspot-optimizer3description: Finds algorithmic complexity and performance hotspots, then optimizes them behind tests without changing behavior. Use for nested loops, repeated scans, N+1 queries, costly re-renders, or when a request mentions hot paths or slow code. Defaults to an analysis-only report.4license: MIT5---67# Hotspot optimizer89Find and (on request) fix complexity/performance hotspots with **behavior preserved and proven by10tests**. Bias toward small, verified wins over broad rewrites.1112## Core rule1314Never change observable behavior. Every optimization preserves outputs, ordering, error semantics,15and public APIs — and is proven by a test that passed before and after.1617## Loop: Triage → Prove → Optimize → Verify18191. **Triage** — get candidate leads fast, then reason about them:20 - First pass (cheap, optional): `python3 scripts/scan_hotspots.py <root> --format json` for a21 ranked multi-language lead list. Treat output as *leads, not proof*.22 - Confirm with `Grep`/`Glob`/`Read`: nested loops over the same data, membership tests in a loop23 (list vs set), sort-in-loop, pairwise comparisons, repeated scans, render recomputation, N+124 queries. Rank by impact (hot path × input size), not raw count.252. **Prove** — before touching hot code, run/author a focused test that pins current behavior and, if26 feasible, a quick timing or complexity witness.273. **Optimize** — apply the smallest localized `Edit` that lowers complexity (see28 `references/optimization-playbook.md`). No drive-by refactors or formatting churn.294. **Verify** — re-run the focused test, then the broad gates (type-check, lint, build, suite). If any30 regresses, revert that change.3132## Subagent fan-out3334For large repos, shard files/dirs across `Task` subagents (read-only). Each returns a ranked findings35list: `file:line`, pattern, estimated current → target complexity, risk. The main agent dedupes and36merges into one ranked plan, then optimizes serially (it owns all edits). Cap concurrency at ~4-637subagents; prefer fewer, broader shards over many tiny ones.3839## Optimization safety checklist4041- Same outputs for the same inputs (including ordering and ties).42- No swallowed/altered exceptions; same error types.43- No new unbounded memory (a set/dict cache must be bounded by the same data).44- Equivalent for empty / single / duplicate / large inputs.45- Public API and call sites unchanged.4647## Analysis-only by default4849Default to a report (see `references/report-template.md`): ranked findings with location, current and50target complexity, risk, and a proposed fix — **but do not edit**. Apply fixes only when the user says51implement / fix / apply / refactor (or pre-approves low-risk wins like list→set membership).5253## Resources5455- `scripts/scan_hotspots.py` — heuristic multi-language hotspot scanner (leads only).56- `references/optimization-playbook.md` — transformation catalog + correctness checks + what-not-to-do.57- `references/report-template.md` — analysis-only report skeleton.
BjornMelin