.github

Use when porting R logic into the Python SportsDataverse package (sdv-py) — e.g. translating an nflfastR / cfbfastR / cfbscrapR / baseballr / hoopR R function, reconciling a fix from the pandas `0.36-live` branch into polars `main`, or re-implementing a modeling recipe (EP/WP/QBR/CPOE) from R. Enforces a parity-test-first workflow (golden fixture from the R output → failing parity test → port → green) and the polars-1x + ID-dtype + no-lookaround conventions. Also covers R numeric fidelity when outputs must match R bit-for-bit (R>=4.0 fround, 80-bit long-double sum, non-na.rm null-poisoning, dplyr group order), stale-fork sibling packages (wbigballR-style), and oracle integrity (a browser/rvest-captured oracle can be corrupt — fix the bug, don't match it). Invoke for "port this R function to polars", "port from nflfastR/bigballR", "reconcile 0.36-live into main", "translate this dplyr/np.select to polars", "re-implement the R model recipe in Python", or when a parity test fails on a handful of rounding-boundar

Use when shipping a change in sportsdataverse-py (sdv-py) — opening, pushing, or merging a PR. Runs the steps in the correct order (regenerate codegen docs, update changelog/docs/tutorials, lint, full pytest, commit + verify it landed, push, triage bot reviews CodeRabbit/Sourcery/Copilot immediately — in parallel with CI, not after it — wait for CI green, confirm merge, write a session note) and never cleans up a branch before the merge is confirmed. Invoke for "ship this", "open/merge the PR", "land this change", or any end-of-change release flow.

Use when executing a model-spine implementation plan (the ClaudeCowork specs/plans backlog — prediction stacks, ratings engines, projection/impact models) or building any oracle-gated analytics module in an SDV repo. Covers the full loop — isolated worktree + baseline, Phase-0 oracle harness (metrics/constants/leakage split/fixtures), per-task TDD with verified commits, oracle gates with the never-lower rule, league-shim parity, mypy/codegen close-out, reviewer pass, and the session restart prompt. Invoke for "implement T<x>", "start the <sport> model spine", "continue the prediction stack", or any multi-phase model build.

Use when capturing an external oracle/validation corpus into committed test fixtures — Torvik/KenPom ratings, ESPN BPI/predictor/odds, market closing lines, MoneyPuck, published RAPM/EPM, or any third-party reference a model gate will assert against. Covers column contracts, Utf8-id discipline, the team/player name-crosswalk recipe (contracting normalizer + candidate keys + alias table + match-rate reporting), rate-limit-aware sampling, and the mandatory provenance README. Invoke for "capture the oracle corpus", "commit the <source> fixtures", or any Task-0-style fixture capture in a model plan.

Use when porting Python logic from the SportsDataverse Python package (sdv-py) into a SportsDataverse R package — cfbfastR, hoopR, wehoop, baseballr, fastRhockey, softballR, etc. Enforces a parity-test-first workflow (golden fixture from the Python output → failing testthat test → port → green) plus the tidyverse/data.table idiom map and R package conventions (roxygen2 docs, snake_case, tibble returns, pkgdown reference coverage). Invoke for "port this to cfbfastR", "translate this polars logic to dplyr", "re-implement the sdv-py parser in R", or "bring this Python fix back to the R package".

Add a CBS Sports (NAPI) league/resource — capture + catalog in sdv-internal-refs/cbs.

Register a new ESPN league family in sdv-py — leagues.yaml row, pre-create package dir + __init__, regenerate, gated live test, verify the drift gate.

Add a Fox Sports (Bifrost) league/sport — capture + catalog in sdv-internal-refs/fox.

Add a league/source for ANY SportsDataverse provider (ESPN, Fox Bifrost, CBS NAPI, Yahoo, 247Sports, Torvik) — capture bodies, generate the returns doc, extend the catalog, scaffold the wrapper.

Add sport-specific tidy parsers for an ESPN sport (soccer/cricket pattern) — parser module + per-sport codegen routing + fixtures + TDD.

Add a Yahoo Sports source — capture + catalog in sdv-internal-refs/yahoo (HTML/JSON scrape).

Use to triage and resolve automated code-review comments that land on a sportsdataverse-py (sdv-py) PR from CodeRabbit or GitHub Copilot — fetch the unresolved review threads, fix the valid ones, reply to (and decline, with rationale) the rest, then resolve each thread. Invoke for "address the coderabbit comments", "resolve the bot reviews", "handle the copilot review", or as the post-CI step in /sdv-ship before merging.

Use when building or extending a dataset in an SDV `-data` repo (nfl-data, cfb-data, hoopR-*-data, wehoop-*-data, fastRhockey-*-data) — the ingest → build → validate → publish pipeline that reads the sibling `-raw` repo tree, writes tidy parquet, and publishes via git commit + per-file gh release upload. Invoke for "build the dataset", "add a data-repo builder", "publish to the release", "reshape raw to data", or "daily processor".

Hardened, provider-agnostic single-body capture for ESPN/Fox/CBS — structured id discovery, error-envelope skip, atomic writes.

Generate a col_name|type|description returns table (Python schema YAML or R roxygen @return) from a sample payload or a live DataFrame's schema.

Scaffold a per-sport intro Jupyter notebook (examples/notebooks/0X_<sport>_intro.ipynb).

Use when converting pandas DataFrame/Series code to polars 1.2+ in a SportsDataverse repo — translating a `df.loc`/`np.select`/`df.assign`/`groupby().transform`/`merge` block, reconciling a pandas fix from the sdv-py `0.36-live` branch into polars `main`, or modernizing a pandas-flavored parser/loader. Invoke for "convert this pandas to polars", "rewrite with polars", "translate pandas df.loc/np.where to polars", "port the 0.36-live pandas code", or "make this use polars instead of pandas".

Use for a fast local sanity sweep on the current changes in sportsdataverse-py (sdv-py) before committing or opening a PR — runs ruff, the mypy ratchet, and the relevant tests scoped to changed files only (not the whole suite). Invoke for "preflight", "quick check before commit", "lint+type+test my changes", or "is this ready to push".

Regenerate sdv-py reference docs, verify the Docusaurus build, and snapshot a versioned archive at release.

Use when cutting a new sportsdataverse-py (sdv-py) PyPI release — bump the version, write the CHANGELOG entry, freeze the docs snapshot, and tag a GitHub Release (which triggers the PyPI publish workflow). Invoke for "cut a release", "release 0.0.x", "ship a new version", "publish to PyPI", or "bump the version and release".

Use when setting up any scraping/backfill job expected to run more than ~3 minutes (ESPN, stats.nba.com/wnba.com, stats.ncaa.org, Savant) — generates a user-executable runbook script with unbuffered timestamped logging, a live watch command, resumable checkpoints, and env-only rate tuning, saving into the owning SDV `-raw` repo's canonical committed tree (not scratch dirs). Invoke for "set up a scrape", "backfill season X", "long scraping job", or "scraper runbook".

Use to manage a chain of stacked PRs in an SDV repo — mapping the stack, merging bottom-up, retargeting + rebasing children after a squash-merge, and re-running the codegen drift gate at each new branch head. Invoke for "merge the stack", "land these stacked PRs", "retarget after merge", "stacked PR status", or when 2+ open PRs base on each other.

Apply the bespoke SportsDataverse pkgdown theming and fix the shared extra.css Bootstrap-5 bugs (dark-mode-invisible text, dead .navbar-dark selectors).

Generate or back-fill a roxygen @return markdown table (col_name|type|description) for an SDV R function, matching the Python returns convention.