# NFL Picks Build Backlog This backlog translates `docs/NFL_FRAMEWORK_PLAN.md` into implementation issues. It is written in GitHub-issue style so the list can be copied into `sacboyz/nfl-picks` once the repo exists remotely. ## Current Implementation Snapshot As of the local fixture build, the repo has completed the foundation, mock runner, report shell, tracking/audit artifacts, market-health artifacts, settlement/backtest fixtures, release docs, release bundle checks, and a one-command quality gate. Still pending for production readiness: - approved live providers and provider-specific schema fixtures - real nflverse/nflreadpy data ingestion beyond fixture boundaries - live odds, weather, injury, and inactive adapters - historical replay with real seasons - provider-backed calibration of thresholds and lifecycle promotion rules - Cloudflare Pages repository configuration after GitHub repo creation ## Milestone 1: Foundation ### Issue 1: Repo Bootstrap And Project Skeleton Labels: `foundation`, `repo` Create the standalone Python project structure for `sacboyz/nfl-picks`. Deliverables: - Python package skeleton. - `pyproject.toml`. - `tests/` directory. - Basic README. - No live API calls. Acceptance criteria: - `python -m pytest` runs. - Package imports cleanly. - No production data dependencies are required. ### Issue 2: Config Constants For V1 Markets And Thresholds Labels: `foundation`, `config`, `markets` Define V1 market scope, deferred markets, baby-line thresholds, edge thresholds, confidence tiers, inactive states, candidate states, and market lifecycle defaults. Acceptance criteria: - Kickers and DST are clearly excluded from V1. - Receptions threshold is exactly `22.5%`. - Pass attempts and completions thresholds are exactly `15%`. - Every NFL market starts as `research` or `watch`, never `trusted`. ### Issue 3: Core Contract Dataclasses Labels: `foundation`, `contracts` Create NFL equivalents of the reusable MLB contract layer. Deliverables: - `SlateContext` - `MarketBlend` - `ModelProjection` - `EngineSignal` - `EngineCandidate` - `CandidateBet` Acceptance criteria: - Candidate fields include inactive state, publish-time line fields, correlation group, confidence tier, data completeness, and injury/opportunity tags. - Contracts do not perform live fetching or business logic. ### Issue 4: Odds And Market Math Labels: `foundation`, `market-line` Implement reusable odds helpers. Acceptance criteria: - American odds convert to implied probability. - Projection vs line determines projected side. - Over/Under implied probabilities determine book lean. - Books-agree logic is test-covered. ### Issue 5: Foundational Gates And Grade/State Mapping Labels: `foundation`, `grading`, `gates` Implement the first executable gate layer. Acceptance criteria: - `ABSTAIN / NO_PLAY` is distinct from Review. - Missing core data forces Abstain. - `PRE_INACTIVES` prevents A grade. - `POST_INACTIVES_INVALIDATED` forces Abstain. - Publish-time edge compression demotes to Review or Abstain. - Low confidence cannot produce A/B. - Team markets produce Lean / Review / No Play only in V1. ## Milestone 2: Static Runner And Report Shape ### Issue 6: Mock Slate Fixture Labels: `fixtures`, `runner` Create static NFL slate fixtures for player props, team bets, inactives, and odds. Acceptance criteria: - Fixtures cover clean A/B candidates, Review, Fade, Abstain, stale projection, and moved-line cases. - No live API calls. ### Issue 7: Static Daily/Window Runner Labels: `runner`, `workflow` Build a local runner that loads mock data and emits evaluated candidates. Acceptance criteria: - Supports game windows: Thursday, Sunday early, Sunday late, SNF, MNF. - Applies inactive state and publish-time line checks. - Produces machine-readable output. ### Issue 8: Initial HTML Report Prototype Labels: `reporting`, `ui` Create a static report inspired by MLB's report grammar. Acceptance criteria: - Includes team context board. - Includes player prop board. - Includes Review/Fade/Abstain sections. - Shows check bars, confidence, best line, and risk flags. - Uses no lock or guarantee language. ## Milestone 3: NFL-Specific Context ### Issue 9: Role / Injury / Opportunity Module Labels: `injuries`, `opportunity`, `context` Implement classifications for injury risk and opportunity creation. Acceptance criteria: - Detects opportunity boost, role upgrade review, usage unclear, and offense downgrade. - Detects opponent injury boost/caution and mismatch states. - Projection predating injury/inactive news review-gates the candidate. ### Issue 10: Defensive Matchup Module Labels: `matchup`, `context` Implement stat-specific matchup color logic. Acceptance criteria: - Rank 1 means most favorable production allowed. - Overs and unders invert color interpretation correctly. - Defensive injury override can move matchup one band. - `sos_adjusted` field is represented even if V1 data is raw. ### Issue 11: Game Script And Correlation Module Labels: `game-script`, `correlation` Implement game-script tags and same-game correlation groups. Acceptance criteria: - QB/WR, game-total/player-prop, and RB/favorite-script groups are tagged. - Contradictory same-game pairs hard-fade unless explicitly overridden. - Correlation group is available to report and tracker output. ## Milestone 4: Data Integration ### Issue 12: nflverse/nflreadpy Baseline Loader Labels: `data`, `projection` Load historical and current NFL data for baseline projections. Acceptance criteria: - Loads schedules, player stats, and team context from nflverse/nflreadpy-compatible sources. - Supports cold-start priors and regression baselines. - No betting recommendations depend on missing core projection inputs. ### Issue 13: Odds Provider Integration Labels: `odds`, `market-line` Integrate the selected sportsbook odds provider for NFL markets. Acceptance criteria: - Fetches h2h, spreads, totals, team totals, and V1 player prop markets. - Preserves best book, best line, best odds. - Stores line at grade and line at publish. ### Issue 14: Injury/Inactives Provider Integration Labels: `injuries`, `inactives` Integrate authoritative injury and inactive state data. Acceptance criteria: - Supports the 90-minute inactive state machine. - Invalidated projections force re-grade or Abstain. - Pre-inactives outputs cannot publish A grades. ## Milestone 5: Tracking And Promotion ### Issue 15: Tracker CSV And Audit JSON Labels: `tracking`, `audit` Create tracker and audit artifacts. Acceptance criteria: - Tracks sport, season, week, window, market, grade, confidence, matchup, injury tag, correlation group, line movement, and result. - Audit JSON includes hidden gate results. ### Issue 16: Market Health And Promotion Rules Labels: `market-health`, `calibration` Build weekly market-health summaries and promotion criteria. Acceptance criteria: - No NFL market starts as trusted. - Promotion from research/watch to trusted requires settled evidence. - Correlated outcomes are de-weighted in summaries. ### Issue 17: Historical Backtest Harness Labels: `backtest`, `calibration` Create a replay harness for historical NFL slates. Acceptance criteria: - Replays weeks by market and game window. - Reports performance by threshold band, matchup color, book agreement, injury tag, and game script. - Produces findings without changing thresholds automatically. ## Production Backlog After Fixture Build ### Issue 18: Approve Live Providers And Add Schema Fixtures Labels: `data`, `providers`, `blocked` Choose approved providers for odds, weather, injury/inactives, and usage/projection data, then add fixture payloads that represent each provider schema before enabling live calls. Acceptance criteria: - `docs/PROVIDER_DECISIONS.md` records each approved provider. - Provider schema fixtures exist for every enabled feed. - Tests cover normalization from provider fixture payloads. - Fixture mode remains the default and requires no secrets. ### Issue 19: Implement Provider-Specific Odds Adapter Labels: `odds`, `provider`, `market-line` Implement the approved odds provider for V1 team markets and player props. Acceptance criteria: - Supports moneyline, spread, game total, team total, and V1 prop markets. - Preserves sportsbook, line, odds, last update, and best-line shopping fields. - Publish-time line gate stores `line_at_grade`, `line_at_publish`, and `edge_at_publish`. - Stale/outlier lines force Review or Abstain when required. ### Issue 20: Implement Official Injury/Inactives Adapter Labels: `injuries`, `inactives`, `provider` Implement the approved injury/inactives provider and connect it to the inactive state machine. Acceptance criteria: - `PRE_INACTIVES`, `POST_INACTIVES_CONFIRMED`, and `POST_INACTIVES_INVALIDATED` are populated from provider data. - Official 90-minute inactive reports can invalidate projections. - Projection source latency versus official inactives is a Review gate. - Next-man-up and opponent defensive injury tags are visible in audit/report output. ### Issue 21: Implement Real nflverse/nflreadpy Baseline Loader Labels: `data`, `projection`, `nflverse` Replace fixture-only baseline inputs with real nflverse/nflreadpy-compatible data loading. Acceptance criteria: - Loads schedules, player usage, team context, and historical baselines for selected seasons/weeks. - Supports cold-start priors and regression to team/position baselines. - Keeps independent projection logic separate from sportsbook confirmation. - Missing core projection inputs force `ABSTAIN / NO_PLAY`. ### Issue 22: Real Historical Replay And Calibration Report Labels: `backtest`, `calibration`, `market-health` Run historical weekly replay with real data and summarize threshold/lifecycle findings without automatically changing config. Acceptance criteria: - Reports by market, grade, confidence, game window, matchup color, book agreement, injury tag, and correlation group. - Correlated outcomes are de-weighted. - Team bets remain Lean / Review / No Play until validated. - Market lifecycle recommendations remain research/watch until minimum settled sample is reached. ### Issue 23: Cloudflare Pages Repository Wiring Labels: `publishing`, `repo` After `sacboyz/nfl-picks` exists on GitHub, configure repository Actions and Cloudflare Pages publishing from `docs/`. Acceptance criteria: - GitHub Actions pass on the remote repo. - Cloudflare Pages publishes static `docs/` output. - `docs/site_map.json` and `docs/mock/release_bundle.json` validate after publish build. ## Recommended Next Build Slice Start with Issue 18 only after provider choices are approved. Until then, keep improving fixture-mode tests, docs, and report UX without introducing live dependencies.