cup26/docs/V5-PLAN.md

Cup26 v5 — 20 features + a stronger model pipeline

Drafted after the v4 upgrade (i18n/DE, recency model, freshness, mobile). Each item ships independently, smallest-risk-first within its phase; the app stays deployable after every commit. Hard constraints stand: bookmaker odds are benchmark-only, squad values stay out of the model, no auto-anything that pretends to be betting advice.

Model improvement: better than a single validation window

Today: params fit pre-2018 → hyperparams tuned on 2018–2022 → tested once on 2022–2026; the shipped model then trains on ALL data with those hyperparams. The weakness is hyperparam selection on ONE window — it can overfit that window's quirks (e.g. the grid-floor ξ result).

v5 scheme — rolling-origin cross-validation (walk-forward CV):

1. Five rolling validation folds: tune-eval on 2014–16, 2016–18, 2018–20, 2020–22, 2022–24, each predicting strictly walk-forward with params fit only on data before the fold. Pick hyperparams by MEAN RPS across folds (ties → fewer parameters), not by a single window.
2. Keep 2024–2026 as the untouched FINAL test, evaluated once, reported honestly in backtest.json (the public Methodology page).
3. Add a final probability-calibration layer: isotonic regression fit walk-forward on the CV folds' predictions, applied at runtime, validated the same way (ship only if mean-fold RPS/ECE improve).
4. Widen what gets tuned (same discipline): HOME_ADV_ELO, the Elo K scale, stage-conditional ensemble weight (group vs knockout), Team-DC window length. All cheap grid axes on cached walks.
5. Shipped model still trains through today + nightly Team-DC refit + live fast-Elo re-rating (v4) — recency at runtime, selection by rolling CV.

The 20 features

A. Live & match experience

1. In-play win-probability timeline — server stores the in-play prob each poll while live; match page draws the momentum curve (the "story of the match" in one chart).
2. Odds-movement chart per match — odds_history is already captured every 3h; plot the de-vigged market line vs our frozen model number from prediction_snapshots.
3. Goal/kickoff notifications (opt-in) — PWA Web Push: pick matches or a team, get goals + kickoff pings (server already knows score changes).
4. Penalty-shootout live view — ESPN summary carries shootout events; render kick-by-kick during shootouts instead of the generic timeline.
5. Upset meter — after each match, how surprising was the result vs the frozen model (RPS percentile); a tournament-wide "biggest shocks" list.

B. Predict & explore

6. Bracket what-if mode — tap winners through the knockout tree; recompute title odds client-side under your picks (matchMatrix runs in the browser).
7. Group qualification scenarios — "X advances if…" engine over the final group matchday (exhaustive enumeration of remaining group results).
8. Team comparison view — two teams side-by-side: Elo trajectory, form, style fingerprint (StatsBomb), squad value, H2H, model matchup.
9. Elo history charts — precompute each WC team's rating path (1872→now, and tournament-zoom) at data:build; sparkline on team pages.
10. H2H explorer — pick any two nations (search), full 150-year record + the model's hypothetical matchup.
11. Golden Boot race — live top-scorer table from ESPN events + historical scorer context per player.
12. Model diary — public log of nightly refits and biggest rating moves ("Morocco +14 after beating Spain"), feeding the transparency story.

C. App & UX

13. Favorite team — star a team: pinned next-match card on Live, its odds evolution, one-tap to its page (localStorage, no accounts).
14. Daily digest view — one screen: yesterday's results + model movement, today's matches with predictions, the title-odds delta.
15. Global search / command palette — Cmd-K + mobile search: jump to any team or match.
16. Timezone-correct schedule everywhere + "my local time" chips and a week-strip calendar view of all 104 fixtures.
17. Offline polish — cache the last snapshot in the SW; show a "stale — last updated X" banner instead of empty states when offline.
18. Accessibility pass — focus rings, aria-labels on all probability bars (text alternatives with real numbers), prefers-reduced-motion, contrast audit in both themes.
19. Performance pass — route-level code-splitting (recharts already lazy), hover/viewport prefetch, list virtualization where >50 cards, font subset.
20. Share links — per-match/per-team canonical URLs with server-rendered OG meta (title + the model's numbers) so shared links unfurl nicely.

Order

Model pipeline first (it gates everything math-adjacent: 1, 5, 6, 12), then B6/B7 (pure client math, high wow), then A1/A2 (data already on disk), then C13–C16, then the rest. Verify per item: tests + build gate + preview matrix (EN/DE × mobile/desktop × themes); deploy in batches of 2-3 features.

Status (June 12, after the first v5 night)

SHIPPED + DEPLOYED: model pipeline (rolling CV confirmed v4; isotonic layer validated LOFO and shipped), 1 in-play timeline, 2 odds-movement chart, 5 upset meter, 6 bracket what-if, 7 qualification scenarios, 8 compare page (doubles as 10 H2H explorer), 9 Elo history charts, 12 model diary, 13 favorite team, 14 daily digest, 15 search palette, 17 offline banner, 18 a11y pass (charts/bars labelled; reduced-motion was already global), 20 share/OG meta.

DEFERRED, with cause:

• 3 notifications (Web Push): needs an SW strategy change (generateSW → importScripts) and real-device permission testing — too risky to land blind on the live site mid-tournament. Next session's headline.
• 4 shootout live view: no real shootout payload exists until the knockouts (June 28+); build against real data then.
• 11 golden boot: ESPN only gives scorer names inside free-text event strings — parsing is fragile; needs a structured source first.
• 16 calendar strip: substantially covered by Predict's day-grouped "All upcoming" view; revisit only if navigation still feels lacking.
• 19 perf pass: bundle is ~476KB main + lazy recharts; fine for a precached PWA. Revisit if Lighthouse says otherwise.