nfl-team-projections AGENTS.md

Agent instructions

You are building an NFL team projection engine in this repository.

Read PROGRESS.md before doing anything else. Build only the first incomplete phase, run its Definition of Done checks, update the log, and stop.

Build protocol

1. Read the current spec in build/.
2. Read the guide sections the spec cites.
3. Build that phase only.
4. Run and print all checks.
5. Append design choices and unresolved issues to DECISIONS.md.
6. Update PROGRESS.md only after results are shown.
7. Stop and wait for the user.

The gates are deliberate. The user must be able to inspect each layer before the next one hides it.

Standing rules

Environment

• Use Python 3.12+, uv, Polars, SQLite, and one run.py entry point.
• Everything runs locally until phase 10.
• Ask before adding a package and explain why the standard library is insufficient.
• All tunable values live in config.yaml.

Data

• Save every raw API response to data/raw/ before parsing it.
• Retain source and retrieval timestamps. An injury report from Friday cannot forecast Thursday.
• Observed postgame weather and realized starters are never valid pregame inputs. Use archived forecasts/statuses with a verifiable availability time, or omit that feature from historical evaluation and label any oracle analysis clearly.
• Never silently drop a row: preserve it with a null and reason code, then report the count.
• Print row counts before and after every transformation.

Correctness

• No leakage. Features for game N use only data knowable before N's kickoff. Shift rolling features; fit transformations inside each training fold.
• Walk-forward only. Never use random train/test splitting.
• Estimate uncertainty. A score mean alone is not a forecast.
• Treat availability as time-sensitive input, not hindsight.

Evaluation

• Compare each layer with explicit baselines and, where possible, de-vigged market probabilities.
• State failures plainly. If a feature does not improve out-of-sample scoring or calibration, remove it or label it experimental.
• Do not produce bankroll curves, ROI, units won, or “locks” from untimestamped price data.