commodity_hindcast — engineer handover

commodity_hindcast produces county-level yield hindcasts and forward-looking forecasts for US row crops (corn, soybean, wheat) plus international commodities (Brazilian soy, Indian wheat, Ghanaian cocoa). Each run replays history under a leak-free walk-forward protocol, fits a residual-mode regressor on top of a NASS-trend baseline, applies conformal calibration, and delivers per-init parquet bundles to S3 for downstream client products. See wiki/commodity_hindcast/synthesis/overview.md for the business rationale and downstream consumers.

Three audience tracks

Pick the track that matches your role and follow its sequence.

Track 1: User Support (you don't write code; you investigate client questions)

1. data_lineage.md — where every input comes from
2. risk_register.md (skim Critical + High only) — what's known to break
3. runbook/forecast_per_init.md — how a forecast is produced
4. wiki/commodity_hindcast/concepts/hindcast_vs_forecast.md — the difference between the two
5. contacts.md — who to escalate to

Track 2: QA / Test (you validate runs and approve releases)

1. runbook/full_hindcast_rerun.md — how a hindcast run is verified
2. runbook/qa_to_prod_sync.md — promotion procedure
3. signoff.md — the acceptance checklist
4. risk_register.md (full read) — what to flag during review
5. diagrams/output/risk_heatmap.png — visual

Track 3: Technical (you write code; you debug; you ship)

1. The 12 explainer-grid panels at /data/processing/tmp/tmi-explainers/output/ch_*.png — start with ch_00_e2e.png
2. decisions/ADR-001 through decisions/ADR-005 — the load-bearing design choices
3. All 5 runbooks under runbook/
4. access.md — every credential and env var you need
5. wiki/domain_model/ and wiki/commodity_hindcast/ — full reference

Document index

Doc	Purpose	Length
data_lineage.md	External sources + ResolvablePath fields	~280 lines
risk_register.md	14 risks, severity-ranked	~250 lines
5 ADRs under decisions/	Retro-documented load-bearing choices	150-200 lines each
5 runbooks under runbook/	Step-by-step operational procedures	280-360 lines each
access.md	Credentials, env vars, dashboards	~290 lines
contacts.md	RACI scaffold (placeholders)	~140 lines
signoff.md	Acceptance checklist	~150 lines
placeholders.md	Aggregated unknowns	TBD (not yet drafted)
diagrams/output/*.png	5 runbook flowcharts + 1 risk heatmap	—
12 explainer panels	Pipeline architecture	—

The runbook flowcharts live at /data/processing/tmp/tmi-handover/diagrams/output/rb_forecast_per_init.png, rb_full_hindcast_rerun.png, rb_multi_year_forecast.png, rb_qa_to_prod_sync.png, rb_mlflow_db_recovery.png — one per runbook, plus risk_heatmap.png.

Your first day

1. Read this page.
2. Pick your track.
3. Run cli run preflight --config configs/<some-test-key>.yaml — confirms env + AWS access.
4. Open signoff.md and walk through it with the outgoing engineer.

Scope reminder

This handover covers commodity_hindcast ONLY. Other models in market_insights_models/ (crop_yield, area_forecast, winter_wheat_area, csb_pipeline) have their own pipelines, owners, and runbooks.

Conventions

• All Python invocations use uv run (never bare python).
• All paths are S3-safe via cloudpathlib.AnyPath.
• INPUT_DATA_DIR must be set; the helper raises if missing.
• British English throughout.

Status

This handover pack was drafted on 2026-05-08 through an Actor/Critic orchestration. See IMPLEMENTATION_PLAN.md for the audit trail and placeholders.md for the unknown items the outgoing engineer needs to fill before sign-off.