run-scenarios

name	run-scenarios
description	Use when the user wants to compute deterministic low/base/high scenario outputs for a PlanExe model — given an extract-parameters-from-full JSON, a generate-bounds JSON, and a generate-calculations Python module — producing a scenario result JSON with inputs, outputs, comparison spread, and warnings

Run Low/Base/High Scenarios

Overview

Wraps the scenario-runner system prompt at system-prompt.txt (next to this file) and applies it to the three artifacts produced by earlier pipeline stages: a validated parameter JSON, a bounds JSON, and a generated Python calculations module. Output is a strict JSON document with one input pool and one output set per scenario (low, base, high), plus a comparison block summarising spread per computed output.

This stage is deterministic — it does not sample distributions. Monte Carlo is a separate later stage.

Stage 6 of the pipeline described in planexe_simulator/README.md.

When to Use

• User asks to "run scenarios", "compute low/base/high outputs", "produce a scenario table", or "see how outputs move with the bounds"
• Pipeline step between generate-bounds / generate-calculations (both clean) and monte-carlo
• User wants a first sanity check that the deterministic model behaves sensibly before sampling

Not for: regenerating any prior artifact (use the corresponding earlier skill), Monte Carlo or distribution sampling (later stage), or critiquing the plan as a whole.

Workflow

1. Get the three input paths. If any are missing, ask. Do not guess. Conventional layout (matches output/<version>/):
   • parameters JSON (e.g. output/v12/parameters.json)
   • bounds JSON (e.g. output/v12/bounds.json)
   • calculations Python module (e.g. output/v12/calculations.py)
2. Read system-prompt.txt (sibling of this SKILL.md). Its scenario semantics, input-pool construction, function-execution order, and output shape are authoritative.
3. Read all three input artifacts.
4. Build the three input pools (low, base, high) per the system prompt's selection rules.
5. Run the calculation functions in input order: recommended_first_calculations first, then derived_questions. Skip-and-warn on missing dependencies, NotImplementedError (for P(...) stubs), inf, or NaN. Do not abort the whole run.
6. Emit the scenario JSON per the system prompt's output shape.
7. Output destination. Default: write to <dir-of-parameters>/scenarios.json next to the input. Print the file path back, plus a one-line summary (output count, warning count).

What gets supplied vs computed (re-stated for emphasis)

Variable type	Source for low/base/high
key_value with bounds entry	bounds value for that scenario
key_value with non-null value, no bounds	the same value for all three scenarios
key_value with null value, no bounds	unresolved → may trigger missing-dependency warning
missing_value_to_estimate with bounds entry	bounds value for that scenario
Output of a generated function	computed from current scenario input pool

The scenario names refer to the input bounds, not "good vs bad" outcomes. High cost is bad; high effectiveness is good. Don't rename to optimistic/pessimistic.

Output Shape (re-stated for emphasis — see system prompt for full detail)

{
  "valid": true,
  "plan_summary": { "plan_name": "...", "plan_type": "..." },
  "scenarios": {
    "low":  { "inputs": {...}, "outputs": {...} },
    "base": { "inputs": {...}, "outputs": {...} },
    "high": { "inputs": {...}, "outputs": {...} }
  },
  "comparison": {
    "outputs": {
      "<output_id>": {
        "low": ..., "base": ..., "high": ...,
        "unit": "...",
        "spread_ratio": <high/low or null>,
        "spread_absolute": <high-low or null>
      }
    }
  },
  "warnings": [
    { "stage": "run_scenarios", "scenario": "low", "calculation": "people_protected",
      "message": "Missing dependency 'voucher_install_success_rate'.", "severity": "WARN" }
  ]
}

Numeric JSON rules: no NaN, no Infinity — write null and add a warning. No currency symbols, no thousands separators. Don't round unless needed for valid JSON.

Common Mistakes

Mistake	Fix
Wrapping output in ```json fences	Raw JSON only
Renaming scenarios to "optimistic / realistic / pessimistic"	Keep low / base / high — those refer to bounds, not outcomes
Aborting on first missing dependency or inf result	Skip the affected function for that scenario; emit a WARN; keep the run going
Inventing values for null key_values that have no bounds	Don't. Mark the dependent calculation as missing
Computing percentage change in comparison	Spec is spread_ratio = high/low and spread_absolute = high-low only
Running Monte Carlo or sampling	This stage is deterministic; sampling lives in monte-carlo
Ignoring NotImplementedError from P(...) stubs	Skip, emit a WARN noting the formula needs monte-carlo
Writing Infinity or NaN into JSON	JSON forbids both — use null and warn
Producing a markdown table or prose explanation	JSON only; the spec forbids prose

Reference

• System prompt (authoritative): system-prompt.txt
• Pipeline overview and "scenario purpose" list: ../../README.md, Stage 6
• Companion skills: ../extract-parameters-from-full/SKILL.md, ../validate-parameters/SKILL.md, ../generate-bounds/SKILL.md, ../generate-calculations/SKILL.md
• Example input set for testing (all from the same run):
  • /Users/neoneye/git/neoneye_lab/planexe_simulator/output/v12/parameters.json
  • /Users/neoneye/git/neoneye_lab/planexe_simulator/output/v12/bounds.json
  • /Users/neoneye/git/neoneye_lab/planexe_simulator/output/v12/calculations.py