| 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
- 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)
- Read
system-prompt.txt (sibling of this SKILL.md). Its scenario semantics, input-pool construction, function-execution order, and output shape are authoritative.
- Read all three input artifacts.
- Build the three input pools (
low, base, high) per the system prompt's selection rules.
- 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.
- Emit the scenario JSON per the system prompt's output shape.
- 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
