Why this exists
High-stakes analysis often fails before the model: the question is underspecified, the data contract is implicit, cleaning choices are hidden, uncertainty is treated as independent, or a recommendation is written because the template expects one.
This repository is a platform-neutral Agent Skill and reproducible research portfolio built around a stricter sequence:
| Principle | System behavior |
|---|---|
| Evidence before method | Declare the question, population, grain, target quantity, horizon, lineage, and claim boundary first |
| Readiness before analysis | Preserve the source, profile quality and privacy, and pause on material transformations |
| Adaptive routes | Add descriptive, diagnostic, predictive, or prescriptive work only when justified |
| Honest endpoints | Accept an evidence request, negative validation, do_not_deploy, or no recommendation |
| Dependent uncertainty | Retain shared time, market, participant, campaign, operational, and spatial shocks |
| Traceable communication | Link claims and accessible figures to JSON, CSV, hashes, and rerunnable code |
The result is not a fixed report generator. It is an evidence-gated orchestration system that can stop, ask for a named decision, or produce a bounded analytical product without upgrading weak evidence into a stronger claim.
Start in three steps
1. Install the Skill
npx skills add limingrui679-design/high-stakes-analytics-decision-lab -g
The Agent Skills installer discovers the compact package under
skills/high-stakes-analytics-decision-lab/:
39 files and about 472 KiB, rather than the full research portfolio. Its
machine-readable file and hash contract is in
bundle-manifest.json.
Use docs/getting-started.md for Codex-specific,
no-install, and direct repository options.
2. Ask for the evidence outcome
$high-stakes-analytics-decision-lab
Run the data-readiness gate on this source, preserve the original file, and
select only the analytical routes the evidence supports. Produce an Evidence
Intelligence Report. Add a Decision Intelligence Brief only if the evidence
and decision context justify one.
Start with the decision or evidence question—not a preferred model. A valid
result may be a bounded action, a pilot requirement, targeted diligence, an
evidence request, negative validation, or do_not_deploy.
3. Review the evidence package
Every complete project keeps the narrative, machine result, visual evidence, and source lineage together:
report.md # primary Evidence Intelligence Report
results.json # machine-readable analytical result
chart-map.json # figure-to-question and source contract
figures/*.svg # accessible analytical visuals
A justified decision layer adds decision-report.md,
decision-results.json, and its own figure contract. It never replaces the
primary evidence product.
Direct repository entry points
| Starting point | Command or guide | Outcome |
|---|---|---|
| Environment audit | python3 scripts/hsadl.py doctor |
Python, runtime, template, write-access, and Skill-footprint checks |
| Safe 60-second walkthrough | python3 scripts/hsadl.py demo --output-dir build/demo |
Synthetic source preservation, contract, quality gate, route, and accessible SVGs; no model or recommendation |
| Question only | python3 scripts/hsadl.py route "<question>" --scope full --output-dir <path> |
Evidence and method blueprint; no invented result |
| Question plus data | python3 scripts/hsadl.py start <data.csv> --question "<question>" --output-dir <path> |
Preserved source, draft contract, readiness profile, and unresolved decisions |
| Existing decision case | python3 scripts/hsadl.py validate <case.json> then python3 scripts/hsadl.py run <case.json> --output-dir <path> |
Validated expected, tail, sensitivity, provenance, and group-impact outputs |
| Worked precedents | Fifteen-project portfolio | Complete source-to-report evidence paths |
How it works
The fixed evidence spine remains stable while the case-specific analytical layer changes.
| Fixed evidence spine | Adaptive case layer |
|---|---|
| Question, population, unit, target quantity, and horizon | Route, fields, methods, and validation |
| Source lineage, quality status, and reproducibility | Figures, report sections, and decision criteria |
| Uncertainty, limitations, and claim boundary | Bounded action, evidence request, or stopping status |
The data gate can stop the workflow
Uploaded row-level data do not go directly into a model. The system preserves the original, establishes a contract, checks grain and keys, profiles quality and privacy, and produces a dry-run remediation plan.
| Gate status | Meaning | Permitted next step |
|---|---|---|
ready |
No material failure under the declared contract | Continue |
ready_with_documented_limitations |
Localized issues remain | Continue with visible limits |
needs_user_confirmation |
A substantive transformation, privacy, or intended-use choice remains | Pause for a named approval or clarification |
blocked |
Grain, key, schema, leakage, or another critical failure invalidates the route | Stop and request corrected evidence |
Only safe normalization can run without approval. Deletion, imputation, outlier treatment, category merging, unit conversion, target correction, and grain changes require explicit action IDs. The processed copy never overwrites the source.
Four routes, no mandatory recommendation
| Route | Question | Required discipline | Valid endpoint |
|---|---|---|---|
| Descriptive | What is happening? | Denominators, coverage, trends, segments, and missingness | Baseline report or evidence request |
| Diagnostic | Why might it be happening? | Contributions, competing explanations, hypotheses, and a visible causal boundary | Prioritized explanations to test |
| Predictive | What is likely next? | Target, horizon, baseline, held-out validation, calibration, subgroup error, and drift | Validated prediction, negative validation, or do_not_deploy |
| Prescriptive | What should be done, if justified? | Owner, alternatives, constraints, dependence, tail risk, sensitivity, and reversal conditions | Bounded action or no decision-ready recommendation |
Routes may compose, but a later route cannot erase the quality and evidence
requirements of an earlier stage. Read the full system design in
docs/architecture.md.
Two products, one evidence contract
| Product | Main question | Contents | Existence rule |
|---|---|---|---|
| Evidence Intelligence Report | What does the evidence establish? | Source and QA contract, methods, validation, figures, uncertainty, limitations, lineage, and reproducibility | Primary record for every complete project |
| Decision Intelligence Brief | What action, pilot, diligence, evidence request, or stop follows? | Decision status, alternatives, constraints, shared shocks, tail risk, sensitivity, and reversal conditions | Conditional; only when a separate decision layer is justified |
Every material figure is generated from the shared editorial evidence system, includes a title and description, and is paired with its analytical question, supported interpretation, and claim boundary. The visual system is part of the evidence contract, not decorative reporting.