/summarize-assessment

name: summarize-assessment
description: Use after the napkin_math pipeline has produced parameters/bounds/scenarios/montecarlo JSON to generate a plan assessment (assessment.md) — a thin interpretation layer over the intermediary artifacts. Emits a JSON manifest, a provenance map, gate verdicts (Critical / Fragile / Marginal / Robust), failure drivers, confidence and trust boundaries, scenario sanity check, and suggested next actions. The artifact is a navigation/judgment file, not a copy of the raw simulation data.

Summarize napkin_math outputs into a plan assessment

Overview

A thin wrapper around `experiments/napkin_math/summarize_assessment.py`. The script reads the pipeline artifacts and emits `assessment.md` next to them. The output is an **interpretation layer**: it tells the next reader of this directory what the simulation tested, which gates fail or pass, which inputs drive the result, which assumptions remain unvalidated, and what to inspect next. The raw distributions live in `montecarlo.json`; `assessment.md` references them via the provenance map rather than reproducing them.

When to Use

• The Monte Carlo stage has just produced `montecarlo.json` and the user wants a verdict
• The user asks "is this plan in trouble?" or "what does the simulation say?"
• After any iteration on bounds or calculations, to see how the gate signals moved

Not for: producing the simulation itself (`monte-carlo`), running scenarios (`run-scenarios`), or extracting parameters from a report.

Workflow

1. **Locate the inputs.** Required: `parameters.json`. Optional but recommended: `bounds.json`, `scenarios.json`, `montecarlo.json`. `validation.json` and `montecarlo_settings.json` are picked up automatically from the same directory if present. The script degrades gracefully if any optional file is missing — it just omits that section. If `parameters.json` is missing, ask.

2. **Invoke the script.** Requires Python 3.11+ (no extra deps):

   /opt/homebrew/bin/python3.11 experiments/napkin_math/summarize_assessment.py \
     --parameters   <path>/parameters.json \
     --bounds       <path>/bounds.json \
     --scenarios    <path>/scenarios.json \
     --montecarlo   <path>/montecarlo.json \
     [--output      <path>/assessment.md]

Default output: `<dir-of-parameters>/assessment.md`. The script prints the output path on stdout.

3. **Report back.** Tell the user the output path. If the user asks for a verdict in-conversation, read `assessment.md` and quote the gate-verdict rows and critical-findings bullets verbatim — don't paraphrase.

How verdicts are decided

Verdicts come from the user's own threshold definitions in the Monte Carlo settings. No identifier-string or unit-string interpretation — domain-bias-free.

Each threshold has an operator (`>=`, `<=`, etc.) and a value. The user wrote the threshold because they want it to pass. The verdict is the pass probability in the simulation:

| Band | Pass probability | Verdict | Note | |---|---|---|---| | ≥ 80% | strong majority | **Robust** | passes in the strong majority of runs | | 50–80% | uncomfortable | **Marginal** | passes more often than not but uncomfortably close | | 20–50% | minority pass | **Fragile** | fails in the majority of runs | | < 20% | rarely passes | **Critical** | rarely passes under current bounds |

Any output classified Critical or Fragile also gets a "bottom line" callout at the top of the report.

The script does **not** invent thresholds for outputs the user did not declare. To get a verdict on an output, declare a threshold on it in the Monte Carlo settings file.

Audience and tone

`assessment.md` is written to be consumed by the next program or process that touches this directory — a downstream pipeline stage, a planning loop, a follow-on extractor, a future invocation of this same workflow. A human can also read it, but the writing optimises for token-density of useful signal over engagement hooks. The output describes **what the file is** (an interpretation layer over the simulation artifacts); it does not label its audience.

What that means concretely:

• The file leads with a machine-readable JSON manifest. Every prose section after it is a structured form of those same signals.
• Stable retrievable section names (`## Critical findings`, `## Gate verdicts`, `## Failure drivers`, `## Suggested next actions`). No colorful or narrative-flavoured headings.
• No reader-engagement prefixes ("If you read nothing else, read this", "Stop and pay attention", "Important:"). The structural markers and verdict labels carry that weight.
• No filler sentences whose only job is to motivate the next sentence. Lead with the substantive claim.
• Keep substantive explanations (what a verdict label means, what a column shows, what makes an item belong in a section). Those are signal, not filler.
• Don't apologise for or hedge the bad news. State it.

Writing rules — apply to the script's output AND to anything you say back to the user about the assessment

These are not stylistic preferences. They are how this skill is meant to communicate.

1. **Critical findings first.** After the artifact contract, machine summary, provenance map, modelling frame, and simulation settings, the first interpretation section is `## Critical findings`. It consolidates every signal that the plan does not survive its own assumptions: Critical and Fragile thresholds, scenario warnings, numbers the model could not compute, and inputs the plan does not supply at all. If nothing qualifies, the section is omitted entirely — silence is the only acceptable form of good news.

2. **No sugar-coating.** A 5% pass probability is "rarely passes under current bounds", not "shows some challenges". A base-scenario value on the wrong side of a declared threshold is "the gate fails at the plan's own central assumptions", not "may warrant further attention". Use the strongest accurate language without overclaiming epistemic