Command

`okulo hotspots`

Rank files by change frequency × complexity — where cleanup usually pays back.

coreprioritization

When to use it

Start of a health pass, sprint planning, or before picking refactor targets.

Usage

okulo hotspots [repo] [options]

Options

Option	Default	Description
`-w, --window`	12m	History window for change frequency
`--top-percent`	10	Share of the ranking marked as hotspots (●)
`--components A,B`	all	Limit ranking to named components
`-n, --limit`	20	Rows to display
`-f, --format`	table	`table` or `json`

Examples

Last six months, top 15 files

okulo hotspots -w 6m -n 15

Backend-only in a monorepo

okulo components
okulo hotspots --components backend -w 6m

Stricter hotspot cut + JSON export

okulo hotspots --top-percent 5 -f json -o hotspots.json

Sample output

Illustrative terminal output (column layout matches the real CLI):

Hotspots  change frequency × complexity
#  file                          score  revs  churn  loc  cognitive  authors  health
─  ────────────────────────────  ─────  ────  ─────  ───  ─────────  ───────  ──────
1  ● src/billing/invoice.py       92.4    48   6120  840        210        6     3.1
2  ● web/checkout/Cart.tsx        71.2    31   4044  520        145        4     4.8
3    server/orders/api.go         58.0    22   2102  310         88        5     6.2
4    lib/auth/session.ts          41.5    14    980  190         42        3     7.4

4 hotspot(s) = top 10% of 120 files · 8% of the code · 47% of all changes · 51% of churn

How to read it

● marks a hotspot (default: top 10% with enough revisions).
score ranks change × complexity — higher means “look here first”, not “bad engineer”.
health is 1–10: ≥8 healthy, 4–8 warning, <4 alert. Pair it with revs: low health + high revs = active pain.
The footer concentration line is the punchline: a small % of files often absorbs most change — that is where refactor ROI is highest.

Tips

Pick 3–5 files, then run debt / refactor / trend --file — do not boil the ocean.
Complex but untouched files are inactive debt; they may not appear as hotspots.

okulo hotspots