Playbook
Strategic Shift Rollout
Coaching clipboard for phased strategic migration tracks and rollout possessions.
Strategic Shift Rollout
This document defines the strategic migration tracks and phased rollout sequence without changing runtime behavior today.
Maintainers only: this rollout clipboard exists for internal sequencing and future migration planning, not for everyday reader workflows.
Read this page as a rollout clipboard
| If you need… | Start here |
|---|---|
| The current state in one glance | Current state |
| The work lanes for future changes | Strategic tracks |
| The rollout order | Phased rollout plan |
| The placeholder flags | Flag-to-track mapping |
Coaching note: Every flag listed here defaults to false. This page is a
rollout clipboard for sequencing work, not an activation guide.
Current state
| Item | Current position |
|---|---|
| Active phase | Phase 0 — Scaffolding only |
| Runtime behavior change | None |
| Feature flag defaults | All listed flags remain false |
| Purpose of this page | Sequence future work before implementation starts |
Strategic tracks
The strategic shift is split into parallel tracks so future migrations can land incrementally:
| Track | What moves in this lane |
|---|---|
| Ingestion track | Source extraction and upstream fetch orchestration updates |
| Storage track | Data persistence and file/database layout migration |
| Schema track | Validation and model evolution for new data contracts |
| Serving track | Downstream access patterns and consumer compatibility |
Phased rollout plan
The phased rollout is intentionally low-risk and backward-compatible:
| Phase | What happens | Expected behavior |
|---|---|---|
| Phase 0 — Scaffolding only (current) | Add config placeholders and documentation artifacts | No behavior changes |
| Phase 1 — Shadow mode | Enable parallel reads/comparisons behind flags | No production writes |
| Phase 2 — Dual-write / controlled cutover | Write to both legacy and strategic paths, validate parity, then route traffic gradually | Controlled overlap with parity validation |
| Phase 3 — Legacy retirement | Remove fallback paths after sustained parity and operational sign-off | Strategic path becomes the only path |
Flag-to-track mapping
Future migrations can be enabled per track or phase using these placeholders:
| Area | Placeholder flag |
|---|---|
| Ingestion track | NBADB_STRATEGIC_TRACK_INGESTION_V2_ENABLED |
| Storage track | NBADB_STRATEGIC_TRACK_STORAGE_V2_ENABLED |
| Schema track | NBADB_STRATEGIC_TRACK_SCHEMA_V2_ENABLED |
| Serving track | NBADB_STRATEGIC_TRACK_SERVING_V2_ENABLED |
| Phase 1 shadow mode | NBADB_STRATEGIC_PHASE_1_SHADOW_MODE_ENABLED |
| Phase 2 dual-write | NBADB_STRATEGIC_PHASE_2_DUAL_WRITE_ENABLED |
All flags default to false, preserving current behavior until explicitly enabled.
Decision log
Each strategic track and phased gate was chosen for a specific reason. This section captures the rationale so future contributors understand why, not just what.
| Decision | Rationale | Alternatives considered |
|---|---|---|
| Four parallel tracks (ingestion, storage, schema, serving) | Tracks are orthogonal -- an ingestion change should never block a schema migration. Parallel lanes let different contributors advance independently. | Single monolithic migration (rejected: too much blast radius per PR). |
| Phase 0 starts with scaffolding only | Introducing config placeholders and docs first ensures the team has a shared vocabulary before any runtime behavior changes. It also makes code review easier -- reviewers see the shape of the change before it does anything. | Jump straight to shadow mode (rejected: no shared understanding of flag semantics). |
| Shadow mode before dual-write | Phase 1 reads both paths in parallel but writes nothing new. This lets the team observe parity metrics with zero risk to production data. | Dual-write from the start (rejected: write-path bugs are harder to roll back than read-path bugs). |
| Dual-write with parity validation | Phase 2 writes to both legacy and strategic paths simultaneously, then compares outputs. The overlap period is intentionally long to catch edge cases that appear only during specific game schedules or season phases. | Cut over in one atomic switch (rejected: NBA data has seasonal patterns that take weeks to surface). |
| Feature flags per track and per phase | Granular flags let operators enable one track (e.g., storage) in one phase (e.g., shadow mode) without affecting other tracks. This avoids the "big bang" activation anti-pattern. | Single global "v2 enabled" flag (rejected: all-or-nothing toggles make rollback coarser). |
| Legacy retirement last | Removing fallback code only after sustained parity and operational sign-off ensures there is always a quick rollback path during the transition. | Remove legacy as soon as parity is confirmed (rejected: parity over a short window can miss long-tail data issues). |
Phase compatibility matrix
Not all phases and tracks can advance at the same time. The matrix below shows which combinations are safe to run in parallel and which require sequential gating.
| Ingestion | Storage | Schema | Serving | |
|---|---|---|---|---|
| Phase 0 (scaffolding) | Parallel | Parallel | Parallel | Parallel |
| Phase 1 (shadow mode) | Parallel | Parallel | Sequential after ingestion | Sequential after schema |
| Phase 2 (dual-write) | Parallel | Sequential after ingestion | Sequential after storage | Sequential after schema |
| Phase 3 (legacy retirement) | Sequential (last) | Sequential (last) | Sequential (last) | Sequential (last) |
Reading the matrix:
- Parallel means the track can enter this phase independently of other tracks in the same phase.
- Sequential after X means the track must wait until track X has completed or stabilized at this phase before advancing.
- Phase 3 is always sequential across all tracks -- legacy code is removed one track at a time after sustained parity confirmation.
Rule of thumb: Within Phase 0 and Phase 1, tracks can generally move independently. Once dual-write begins in Phase 2, downstream tracks must wait for upstream tracks to stabilize. Legacy retirement in Phase 3 always proceeds one track at a time to limit blast radius.
Monitoring checklist
Each phase transition has a specific set of checkpoints. Do not advance to the next phase until every item is confirmed.
Phase 0 to Phase 1 (scaffolding to shadow mode)
- All placeholder flags are present in configuration and default to
false - Documentation pages (this page, architecture, onboarding hub) reference the strategic tracks
- At least one integration test exercises the flag-reading code path
- Team members have reviewed and acknowledged the rollout plan
Phase 1 to Phase 2 (shadow mode to dual-write)
- Shadow reads have been running for a minimum of two full game-weeks
- Parity metrics show less than 0.1% divergence between legacy and strategic read paths
- No P0 or P1 issues attributed to shadow-mode code in the incident log
- Write-path implementation has been code-reviewed by at least two contributors
- Rollback runbook is documented in the Troubleshooting Playbook
Phase 2 to Phase 3 (dual-write to legacy retirement)
- Dual-write has been active for a minimum of four full game-weeks (covering varied schedule density)
- Row-level parity checks pass at 100% for all tables in the affected track
- Strategic path has handled at least one "stress event" (e.g., a full game day with 15 games)
- Operational team has signed off that monitoring, alerting, and on-call runbooks are updated
- No open issues referencing dual-write inconsistencies
- Legacy code removal PR is scoped to a single track (no multi-track removals in one PR)
Rollout cues to keep nearby
- Land flags and documentation before behavior changes.
- Keep parity checks in front of cutover decisions.
- Treat legacy retirement as the last possession, not the first sign of momentum.
- Use this page to coordinate sequencing, not to imply that any future phase is already active.
- When in doubt, extend a phase rather than compressing the next one -- patience is cheaper than incidents.
Related routes
- Architecture for the current source-to-export system view
- Role-Based Onboarding Hub for stakeholder and contributor handoff routes
- Troubleshooting Playbook when rollout work introduces operational misses
Keep moving
Stay in the same possession
Keep the mental model warm with adjacent pages, section hubs, and search-friendly routes into the same topic cluster.
Analytics Quickstart
Land quick wins fast and move from setup to analysis with intent.
SQL Playground
Rehearse DuckDB syntax and query structure in the browser before touching the full warehouse.
DuckDB Query Examples
Move from the browser sandbox into real warehouse query patterns and analyst-ready examples.