Skip to content

Handover sign-off — commodity_hindcast

Outgoing engineer: [PLACEHOLDER] Incoming engineer: [PLACEHOLDER] Handover window: [PLACEHOLDER: 30-day overlap recommended; first 14 days training, last 14 days supervised transition]

Tick each box only when the listed evidence has been seen by both parties. Each item is sized to fit inside a single working day. Where an item references a runbook, the runbook is the source of truth for the exact commands; this page records only that the demonstration happened.

Order of operations:

  1. Work through Section A as a desk-based reading exercise across the first week.
  2. Work through Section B together at the keyboard. The outgoing engineer drives the first run; the incoming engineer drives the repeat.
  3. Section C is done by the incoming engineer alone, on their own machine, against the QA stack only.
  4. Section D is a verbal walk-through against risk_register.md. The incoming engineer must be able to state, in their own words, what the risk is and where it lives in the code.
  5. Section E is the final tidy-up before signature.
  6. Section F is countersigned in the same sitting.

A. Documentation walkthrough

The incoming engineer has read and can navigate to the right section unaided:

  • HANDOVER.md (top-level navigation index) — ___ (initials, date)
  • drafts/data_lineage.md (NASS / WASDE / weather / boundaries -> features -> run_dir -> delivery) — ___
  • drafts/risk_register.md (R1..R7, severity, owners) — ___
  • drafts/access.md (AWS account, ECR, MLflow, env vars) — ___
  • drafts/contacts.md (escalation paths, on-call) — ___
  • drafts/decisions/ADR-001 walk-forward bypass — ___
  • drafts/decisions/ADR-002 calibration result persistence — ___
  • drafts/decisions/ADR-003 mandatory residual mode — ___
  • drafts/decisions/ADR-004 forecast path restructure — ___
  • drafts/decisions/ADR-005 fit production endpoint — ___
  • All 5 runbooks under drafts/runbook/ opened and skimmed — ___
  • All 12 explainer-grid panels under tmi-explainers/output/ch_00..ch_11 viewed — ___
  • All 6 diagram PNGs under diagrams/output/ viewed (5 runbook flows + risk heatmap) — ___

B. Demonstrable operations

The outgoing engineer has demonstrated, with the incoming engineer driving the keyboard for at least the final repetition:

  • Pre-flight check: cli run preflight --config configs/<key>.yaml against a known-good config — see runbook/full_hindcast_rerun.md step 1 — ___
  • Fresh hindcast end-to-end via make hindcast EXPERIMENT_KEY=<key> (corn_usa_smoke or equivalent short config) — see runbook/full_hindcast_rerun.md — ___
  • Single forecast init: cli run forecast --run-dir <run_dir> --season-year <yyyy> --init-date <yyyy-mm-dd> — see runbook/forecast_per_init.md — ___
  • Multi-year forecast loop over a 2- or 3-year window — see runbook/multi_year_forecast.md — ___
  • Regenerate a delivery CSV from an existing run_dir without retraining — see runbook/full_hindcast_rerun.md (deliver-only path) — ___
  • Drill MLflow DB recovery on a copy of mlruns.db in /tmp (do NOT touch the live DB) — see runbook/mlflow_db_recovery.md — ___
  • Walk through QA -> prod sync as DRY RUN only (aws s3 sync --dryrun) — see runbook/qa_to_prod_sync.md — ___

C. Access verified

The incoming engineer has logged in from their own laptop or EC2 and confirmed:

  • AWS account 390844765299 reachable: aws s3 ls s3://qa-treefera-greenprint-data/ returns a listing — see access.md — ___
  • ECR registry 390844765299.dkr.ecr.us-east-2.amazonaws.com login works via bash dev_tools/ecr-login.sh — see access.md — ___
  • MLflow tracking via local SQLite at mlruns.db opens and lists experiments (mlflow experiments search) — see access.md — ___
  • Env vars set: INPUT_DATA_DIR points at the repo root and CROP_YIELD_GEOBOUNDARIES_FILE resolves — see access.md — ___
  • Streamlit app launches locally with PYTHONPATH=<repo_root> and both data env vars set — ___
  • CLI smoke test: cli run preflight --config configs/corn_usa.yaml exits 0 — ___
  • Slack channels joined: [PLACEHOLDER: replace with concrete channel names per contacts.md] — ___
  • PagerDuty service membership confirmed: [PLACEHOLDER: service name per contacts.md] — ___

D. Open known risks acknowledged

The incoming engineer has read and signed off on the open Critical and High risks in risk_register.md:

  • R1 (Critical): TMI selection-bias correction — sign/magnitude mismatch vs QUBE driven by upstream NaN dropouts — ___
  • R2 (High): DESIGN.md vs code drift on national.parquet schema and producer — ___
  • R3 (High): S3 path anchoring on local-only sinks (sqlite, lockfiles, scratch dirs) — ___
  • R4 (High): MLflow SQLite locking on parallel same-commodity runs — ___
  • R5 (High): walk-forward bypass behaviour per ADR-001 still load-bearing — ___
  • R6 (High): wheat sub-types listed in config but not produced by preprocessor — ___
  • R7 (High): non-US geometry requires the all-countries geoboundaries parquet — ___

E. Placeholders accepted or filled

  • Every [PLACEHOLDER] marker across the handover docs has been EITHER filled by the outgoing engineer OR explicitly accepted as out-of-scope by the incoming engineer (cross-reference placeholders.md) — ___

F. Final sign-off

Role Name Email Signature Date
Outgoing engineer [PLACEHOLDER] [PLACEHOLDER] ___ ___
Incoming engineer [PLACEHOLDER] [PLACEHOLDER] ___ ___
Witness / line manager [PLACEHOLDER] [PLACEHOLDER] ___ ___