Output Directory Schema

Each pipeline run creates a timestamped directory under the configured output_dir:

<output_dir>/<run_name>_<YYYYMMDD_HHMMSS>

The timestamp is generated in UTC. The runner creates every stage directory up front, then updates run_manifest.json as stages start, complete, skip, or fail.

Directory tree

results/
  geo_panel_baseline_20260308_153000/
    run_manifest.json
    00_run_metadata/
    05_prior_sensitivity/
    08_ai_advisor/
    10_pre_diagnostics/
    20_model_fit/
    30_model_assessment/
    35_holdout_validation/
    40_decomposition/
    50_diagnostics/
    60_response_curves/
    70_optimisation/
    80_interpretation/
    90_ai_advisor/
    scenario_planner/
      recipes/
        <recipe>_<timestamp>/

scenario_planner/recipes/ is a post-fit evidence area, not a pipeline stage. It appears only after a user evaluates a retained scenario recipe. Recipe evaluation does not mutate run_manifest.json or refit the model.

Stage directories

See Runner Overview for the stage order and optionality.

Post-fit scenario recipe bundles

Each recipe evaluation creates a new directory under scenario_planner/recipes/. It contains the resolved request, validation evidence, fitted estimator manifest, allocation tables, posterior media-contribution summaries with 94% highest-density intervals, a versioned dashboard payload, and a SHA-256 artefact manifest.

See Comparison Outputs for the complete file contract and interpretation boundary.

Main artefacts by stage

00_run_metadata

Main files:

• a copy of the original config under its source filename
• config.original.yaml
• config.resolved.yaml
• session_info.txt
• dataset_metadata.json
• model_metadata.json
• data_dictionary.csv
• design_matrix_manifest.csv
• spec_summary.csv
• estimator_summary.txt and estimator_manifest.yaml for named estimators
• estimator_estimability.csv for the resolved estimator screen summary
• holiday_feature_manifest.csv when holidays are configured

config.resolved.yaml normalises configured data and holiday paths to absolute paths and records the effective sampler configuration on the model.

05_prior_sensitivity

Main files:

• scenario_manifest.yaml
• llm_safe_scenario_manifest.yaml
• <scenario_name>/config.resolved.yaml for each generated or declared scenario

This stage is optional. When prior_sensitivity is absent or disabled in YAML, the directory still exists and the stage is marked skipped.

scenario_manifest.yaml is the local, human-readable manifest. It can include scenario descriptions and raw override paths. Use llm_safe_scenario_manifest.yaml when passing scenario context to an external LLM because it aliases override paths and avoids free-text scenario prose.

08_ai_advisor

This optional stage writes evidence.json, rules_summary.json and advisor_status.json. It performs deterministic preparation checks only. It never calls a provider or proposes a patch. When ai_advisor is absent or disabled, the stage is marked skipped.

10_pre_diagnostics

Main files:

• prior_predictive.nc
• prior_predictive.png
• fixed_effects_estimability.csv and fixed_effects_estimability.json for FE
• cre_structural_estimability.json, cre_reference_estimability.json, and cre_reference_estimability_features.csv for CRE

20_model_fit

Main files:

• model.nc
• trace.png
• posterior_summary.csv
• cre_postfit_estimability.json for CRE

posterior_summary.csv is intentionally compact. It summarizes structural posterior parameters such as adstock, saturation, seasonality, holiday, and likelihood terms, and omits per-date deterministic series like weekly channel contributions or fitted paths. Use the assessment and decomposition stages for time-indexed fitted or contribution outputs.

30_model_assessment

Main files:

• posterior_predictive.nc
• posterior_predictive.png
• posterior_predictive_summary.csv
• observed.csv
• fitted.csv
• fit_timeseries.png
• fit_scatter.png
• residuals.csv
• residuals_timeseries.png
• residuals_hist.png
• residuals_vs_fitted.png

This stage is the in-sample or training-fit assessment. It uses the same data the model was fit on and should not be read as the pipeline’s out-of-sample validation layer.

35_holdout_validation

Main files:

• validation_metadata.json
• holdout_posterior_predictive.nc
• holdout_predictive_summary.csv
• holdout_predictive_report.json
• holdout_observed.csv
• holdout_fitted.csv
• holdout_residuals.csv
• holdout_timeseries.png
• holdout_residuals_acf.png

The holdout summary and report include uncertainty-aware metrics such as crps, bias, and fixed coverage columns for coverage_50, coverage_80, and coverage_94.

This stage is optional. When validation is absent or disabled in YAML, the directory still exists and the stage is marked skipped.

For interpretation guidance and practical rules of thumb, see Blocked Holdout Validation.

40_decomposition

Main files:

• waterfall_components_decomposition.png
• weekly_media_contribution.png
• channel_contributions.csv
• baseline_contributions.csv
• mean_contributions_over_time.csv
• cre_adjustment_contributions.csv for CRE
• cre_decomposition_reconciliation.csv and cre_decomposition_reconciliation.json for CRE

The CRE adjustment is retained on the baseline or non-incremental side of the decomposition. Do not report it as an incremental media contribution.

50_diagnostics

Main files:

• design_summary.csv
• design_report.json
• vif_report.csv
• mcmc_summary.csv
• mcmc_report.json
• bayesian_criteria_summary.csv
• bayesian_criteria_report.json
• elpd_summary.csv (the same summary table)
• predictive_summary.csv
• predictive_report.json
• residual_diagnostics.csv
• residuals_acf.png
• diagnostics_report.csv
• diagnostic_gates.resolved.yaml
• diagnostics_summary.txt
• chain_diagnostics.txt

The design-oriented files are raw input screening outputs. In particular, diagnostics_report.csv labels the corresponding phase as raw_input_screening rather than design.

diagnostic_gates.resolved.yaml records the profile name, source, inline override status, exact boundary rule, and effective warn/fail values used for each check. It is the audit trail for the run’s diagnostic decisions.

60_response_curves

Main files:

• saturation_curve.nc
• saturation_curve_summary.csv
• saturation_curve.png
• forward_pass_contribution_curve.nc
• forward_pass_contribution_curve_summary.csv
• forward_pass_contribution_curve.png
• adstock_curve.nc
• adstock_curve_summary.csv
• adstock_curve.png

These artefacts are intentionally different:

• saturation_curve.* is the sampled saturation transformation on the scaled channel axis, exported with original-scale contribution values for easier reading. The PNG overlays that saturation-only curve against posterior mean realised contributions.
• forward_pass_contribution_curve.* is a full-model direct contribution artefact. It rescales the observed historical spend path from 0% to 200%, runs that spend through the fitted adstock and saturation path, and records the resulting total channel contribution in original target units.
• adstock_curve.* is the sampled carryover-weight profile for one impulse.

70_optimisation

This directory is present for every run, but the stage is skipped unless the YAML config contains an optimization block.

Main files when the stage runs:

• optimized_allocation.nc
• optimized_allocation.csv
• response_distribution.nc
• optimize_result.json
• budget_summary.csv
• budget_response_points.csv
• budget_impact.csv
• budget_bounds_audit.csv
• budget_roi_cpa.csv
• budget_response_curves.csv
• budget_mroi.csv
• budget_optimisation.json
• several PNG plots for allocation, contribution over time, response curves, impact, bounds audit, and ROI or CPA

80_interpretation

This final stage writes evidence_inventory.md and interpretation_report.md. Both files currently contain the same evidence inventory. They report earlier stage statuses and the holdout-validation status, and remind the analyst to review retained evidence before making decisions. They do not compute a business conclusion or establish causal identification. If an earlier stage fails, this stage is not reached.

run_manifest.json

The manifest is the machine-readable index for the whole run.

Top-level fields include:

data includes:

• x_shape
• y_length
• target_column
• x_columns

Stage records

Each stage record contains:

The artifacts mapping uses root-relative paths such as 20_model_fit/model.nc.

Stage statuses

Common cases:

• Stage 35 is skipped when validation is missing or disabled from YAML.
• Stage 70 is skipped when optimization is missing from YAML.
• Later stages become not_reached after the first failure.

Practical use

Use the run directory when you want:

• a stable folder for downstream reporting
• a machine-readable audit trail through run_manifest.json
• stage-level links to artefacts without hard-coding filenames

If you want to add new artefact types or stages, see Extending the Runner.

90_ai_advisor

The advisor guide explains the evidence requirements. The stage also writes advisor_review.md, parameter_identification.json, parameter_identification.md and parameter_lookup.local.json. These local reports remain available when LLM calls are disabled or fail. The parameter lookup contains original names and is excluded from provider evidence.

Main files:

• diagnostics_evidence.json
• diagnostics_rules_summary.json
• diagnostics_advisor_status.json
• diagnostics_advisor_response.json, when an LLM advisor call succeeds
• <provider>_diagnostics_response.raw.json, when an LLM advisor call succeeds
• diagnostics_advisor_error.json, when the LLM call fails
• config_patch_proposal.yaml and approval_request.yaml, when a valid prior patch is proposed
• config_patch_error.json, when a proposed patch is invalid

This stage runs after 80_interpretation by default for enabled ai_advisor blocks. advisor_review.md is the single main report. Technical evidence remains in separate JSON and parameter reports. Set ai_advisor.diagnostics_review_enabled: false to skip it.

The diagnostics advisor evidence is restricted to anonymized channel aliases, convergence counts, normalized predictive metrics, coverage metrics, and scale-free design diagnostics. Raw target-scale fit errors are intentionally excluded from the LLM payload.

The advisor separates computational reliability, raw-design identification risk, predictive evidence, residual structure, prior robustness, and causal identification. Its deterministic decision state is a floor: the LLM can make the result stricter, but cannot soften a failed or warning gate.