Background
gain --weak-filters (just landed in PR #150) ranks tools by leaked tokens. history.db contains 17K+ rows of empirical truth about every filter invocation. Today we report aggregates and the leaderboard; the patterns in the data go un-surfaced.
The substrate is already there — what's missing is the narrative layer that surfaces actionable patterns directly to the user.
Problem
A user reading gain output sees totals. They don't see:
Proposed Design (clean-room)
New gain --insights mode. Each insight is a function:
fn insight_proxy_overuse(tracker: &Tracker) -> Option<Insight> { ... }
fn insight_target_below_release_boundary(...) -> Option<Insight> { ... }
fn insight_target_vs_actual(...) -> Option<Insight> { ... }Each returns Some(Insight { headline, evidence, action }) if the pattern fires.
Output:
ContextCrawler Insights — patterns in your usage
════════════════════════════════════════════════════════════════
• `ls -la target/debug/deps/` ran 8× today, all 39% saved.
→ This is your biggest absolute leak. See #?? for proposed fix.
• `proxy cargo` ran 166× lifetime (4.0M leaked, 0% saved).
→ If unintentional, drop `proxy` prefix. If intentional (filter debugging), ignore.
• `git show <ref>:<path>` saves 47% vs 80% target across 221 invocations.
→ File-content reads in git show output don't route through read filter. See #??.
JSON output (--insights --format json) for downstream consumption — dashboards, scripts, or piping into other tools.
Why now
Effort
S-M (2-4 days). Define ~10-15 patterns, narrative formatter, JSON exporter, snapshot tests on synthetic histories.
Out of scope
Background
gain --weak-filters(just landed in PR #150) ranks tools by leaked tokens.history.dbcontains 17K+ rows of empirical truth about every filter invocation. Today we report aggregates and the leaderboard; the patterns in the data go un-surfaced.The substrate is already there — what's missing is the narrative layer that surfaces actionable patterns directly to the user.
Problem
A user reading
gainoutput sees totals. They don't see:ls target/debug/deps/"git showsavings from 12% → 47%"proxy990 times — 4.0M of that isproxy cargo. Was that intentional?"git show <ref>:<path>consistently saves 47% (vs 80% target). File an issue?"readfilter has a long tail of >50K-token inputs that the 80/80 head/tail cap doesn't handle — see feat(read): --intent flag for surgical extraction on large files #157"Proposed Design (clean-room)
New
gain --insightsmode. Each insight is a function:Each returns
Some(Insight { headline, evidence, action })if the pattern fires.Output:
JSON output (
--insights --format json) for downstream consumption — dashboards, scripts, or piping into other tools.Why now
Effort
S-M (2-4 days). Define ~10-15 patterns, narrative formatter, JSON exporter, snapshot tests on synthetic histories.
Out of scope