Recommendation Scoring#

Overview#

Decant surfaces up to 12 signal recommendations per run, ranked by a numeric score and drawn from a pool of independently-computed signal generators 1. Each generator applies its own eligibility filter and scoring formula; the results are merged, sorted descending by score, and sliced to the top 12 2. All signals look at a rolling 30-day window 3.

The two Recommendation kinds are:

• signal — data-derived from the session archive; scored and ranked.
• catalog — evergreen best-practice suggestions; always score: 0 and appended after signals 4.

Signal Generators and Their Scores#

All generators live in src/recommendations.ts.

Error Hotspots — rate × calls#

errorHotspots() is the highest-priority signal class. Eligibility: a tool must have ≥ 20 calls and an error rate ≥ 12%. Score formula:

score = (errors / calls) × calls // i.e. raw error count

5

A tool with a 50% error rate on 200 calls scores 100, while a 12% rate on 20 calls scores 2.4. This means tools with both high rates and high volume consistently surface at the top.

Churn Files — editors × 1.5#

churnFiles() finds files edited in ≥ 6 distinct sessions in the window. Score: editors × 1.5 6. A file edited in 10 sessions scores 15.

Hot Context Files — readers#

hotContextFiles() finds files read in ≥ 8 sessions with ≤ 2 edit sessions — stable context being re-derived every time. Score: readers 7. Up to 2 files are emitted.

Search-Heavy Usage — ratio × 2#

searchHeavy() triggers when Grep/Glob calls-per-session exceeds 5.0 (with a minimum of 20 sessions in the window). Score: ratio × 2 8. At a ratio of 8 searches/session the score is 16.

Abandoned Rate — pct / 3#

abandonedRate() triggers when the abandoned-session share exceeds 25%, with a minimum of 10 classified sessions. Score: pct / 3 9. A 60% abandon rate scores 20.

Ingest Health — affected × 2#

ingestHealth() triggers when ≥ 10% of sessions carry ingest diagnostics, with a minimum of 15 sessions in the window. Score: affected × 2 10.

Cost Concentration — fixed 5#

costConcentration() triggers when a single model accounts for ≥ 40% of total estimated spend. Score is a fixed 5 regardless of the concentration percentage 11.

Heavy-Tool and Heavy-Server Flattening#

heavyTools and heavyServers are intentionally scored below the issue-oriented signals to prevent high usage volume from outranking genuine problems.

Both generators use a flat score of 2 1213 regardless of call volume. Usage volume alone is not a problem, so these signals are kept at a fixed floor that loses to every issue-flagging signal. An error hotspot with a 12% rate on 20 calls (the minimum eligibility) scores 2.4 and outranks any usage signal; a tool with 2000 calls at 0% errors still scores 2.

heavyTools is also capped at the top 2 non-MCP tools 14 and heavyServers at the top 3 MCP servers 15 before any threshold check.

Final Ranking#

After all generators run, the merged list is sorted by:

1. score descending
2. key ascending (lexicographic tiebreaker) 16

The top 12 are returned 17. Catalog recommendations are appended with score: 0 and displayed after all signals.

Key Source#

• src/recommendations.ts — all signal generators, scoring formulas, eligibility thresholds, and the signals() aggregator.