Explanation: Stage-Gated Workflow
AMMM V2 follows a stage-gated Bayesian workflow. Each stage writes artefacts to a numbered folder, and downstream interpretation is valid only when upstream diagnostics are acceptable.
Stage Map
Section titled “Stage Map”| Conceptual stage | Folder | Purpose |
|---|---|---|
| Stage 0 | 00_run_metadata/ | Problem framing, configuration, provenance, run metadata. |
| Stage 1 | 10_pre_diagnostics/ | Data checks, stationarity, VIF, transfer entropy, prior predictive checks. |
| Stage 2 | 20_model_fit/ | Posterior sampling artefacts and posterior parameter summaries. |
| Stage 3 | 30_model_assessment/ | Posterior predictive fit diagnostics and fit metrics. |
| Stage 4 | 40_decomposition/ | Attribution-style decomposition and channel performance summaries. |
| Stage 5 | 50_diagnostics/ | Convergence, calibration, Pareto k, pair plots, residual structure checks. |
| Stage 6 | 60_response_curves/ | Spend-response curve artefacts by channel. |
| Stage 7 | 70_optimisation/ | Budget optimisation and scenario planning outputs. |
| Stage 8 | 80_interpretation/ | Narrative and governance artefacts (including agentic reports when enabled). |
Gate Framework (g1–g7)
Section titled “Gate Framework (g1–g7)”AMMM diagnostic gates align with a principled Bayesian workflow interpretation:
- g1: prior predictive plausibility.
- g2: R-hat convergence quality.
- g3: effective sample size adequacy.
- g4: divergence-free posterior geometry.
- g5: calibration quality (PIT and coverage).
- g6: PSIS-LOO reliability (Pareto k).
- g7: energy geometry review (BFMI-style assessment from energy diagnostics).
These gates support pass/warn/fail reasoning. Machine-readable outputs are especially important for automation.
Machine-Readable Gate Artefacts
Section titled “Machine-Readable Gate Artefacts”The most important gate artefacts are:
50_diagnostics/convergence_report.json- top-level field:
converged
- top-level field:
50_diagnostics/calibration_report.json- top-level field:
well_calibrated
- top-level field:
50_diagnostics/pareto_k_summary.json- top-level field:
ok
- top-level field:
These fields allow downstream stages and reporting systems to condition interpretation on diagnostic status.
diagnostics_gating Policy
Section titled “diagnostics_gating Policy”diagnostics_gating controls operational gate behaviour:
strict: halt pipeline on convergence failure.warn: continue execution but surface diagnostic warnings.off: disable gate enforcement.
Current V2 workflow enforces strict halting directly on convergence (converged = false). Other diagnostics are still generated and surfaced for governance.
Dependency Logic
Section titled “Dependency Logic”The intended dependency chain is:
- Data and prior checks first.
- Posterior fit second.
- Convergence and calibration review before business interpretation.
- Decomposition/optimisation/reporting consumed under diagnostic context.
If Stage 5 diagnostics are poor, Stage 6–8 outputs should be treated as provisional.
Why This Matters
Section titled “Why This Matters”Stage gating helps prevent a common MMM anti-pattern: producing polished business outputs from unstable posterior inference.
The workflow is therefore designed to make quality failures visible, auditable, and difficult to ignore.
Causal Caveat
Section titled “Causal Caveat”Passing all gates indicates computational reliability and model adequacy under assumptions. It does not establish causal identification by itself.