Prize Stats: every blank, filled

The problem

The scoring was already automated. The gap was data.

Each week, both leagues play a side challenge, such as most combined rushing yards from a team's two starting running backs. A scheduled automation already pulls each league's scores and rosters and drafts the weekly announcement.

One league's platform returns raw stats; the other returns fantasy points only. Some stats, like a quarterback's longest completion, come from neither. Wherever the data had no answer, the automation left a blank, and I filled it by hand: 5 of 15 weekly challenges leave at least one league blank, and one of them is blank in both.

Discovery

I audited all 15 weekly challenges against what each platform's data can answer.

Most challenges were already covered; the gaps clustered in raw player stats.

The other 10 challenges, plus a weekly elimination game, run on team scores and fantasy points both platforms already provide. The audit also showed the challenges reduce to 7 rule shapes, such as a sum of one stat across fixed lineup slots, or an exact count with a position priority. That shaped the data model.

Key decisions

I wrote the PRD as a decision record: the problem with its number, goals and non-goals, a golden test set, and a staged rollout with a kill switch I own.

• Build only for the gaps. The existing automation already handled 10 of 15 weeks; rebuilding them added risk and no value.
• Data API first, AI layers later. v1 has one correct answer per week, so it needs exact logic and tests, not a model. An MCP layer and retrieval only make sense once there is trusted data under them.
• Prize rules as data. Both leagues share one codebase, and a new challenge is configuration rather than code.
• Flag, never guess. A player who cannot be matched comes back flagged for a human. A wrong winner announced to the league costs more than a blank.
• Free managed Postgres over HTTP. Neon's free plan fits a once-a-week workload, and its HTTP driver works on serverless hosts.
• Starters only, slot-aware. Bench and flex rules differ by challenge, so the API takes each starter's lineup slot as input.

The API design

Five endpoints cover v1. Each answers a question the weekly scoring actually asks, and every response says how fresh its data is.

The caller sends starters by lineup slot, the same way the league platforms report them:

POST /weeks/2/fill
x-api-key: <key>

{ "measure": "rush_yards",
  "starters": [
    { "manager": "Team 1", "slot": "RB1", "name": "Chase Brown" },
    { "manager": "Team 1", "slot": "RB2", "name": "Aaron Jones Sr." } ] }

The response ranks the teams, shows each player's matched stat line, and says whether the result is complete:

{ "week": 2, "measure": "rush_yards",
  "stats_refreshed_at": "2026-10-22T04:12:02Z",
  "complete": true,
  "teams": [ { "manager": "Team 1", "total": 185, "complete": true,
    "players": [ { "slot": "RB1", "name": "Chase Brown", "value": 80 },
                 { "slot": "RB2", "name": "Aaron Jones Sr.", "value": 105 } ] } ] }

• One generic fill endpoint, not one per challenge. The stat is a parameter, so a new challenge on an existing stat needs no new endpoint.
• Unmatched players come back as data, not errors. A player with no stat line returns an empty value with a plain-language flag, and the team is marked incomplete, so the caller can still post everything else.
• Freshness on every response. A refresh timestamp lets a reader see whether a stat correction could still change the result.
• Key auth on everything except health. A host or a person can check the service is up without holding a key.

Validation

The API had to earn trust against answers I already knew before it could replace any hand-filled cell.

• Golden set. Every prize result already settled by hand this season, weeks 1 to 6 in both leagues, 12 results in all. The API must match every one before it fills a live week.
• The shared-name catch. In the week 5 backtest, the API refused to score Justin Jefferson. Two active NFL players share the name, a wide receiver and a linebacker, and League B's platform does not send a player's NFL team. Instead of guessing, the API flagged him.
• A domain rule settled it. Neither league has individual defensive player slots, so a defender can never be a fantasy starter. Excluding defenders, and using the lineup slot to break other ties, resolved the case. Two offensive players with one name in a flex slot are still flagged.
• Regression check. After each change I re-ran both backtested weeks, and the totals did not move.

Where it stands

What I took from it: the most useful early work was the audit, not the code; a result with one right answer is better served by exact logic than a model; and a flag that asks for a human is worth more to a league than a confident wrong winner.