Numeric execution layer for HEP workspace projects: numerical scans, scan-config validation, constraint decisions, exclusion plots, and analysis summary generation. Use this skill when the user asks for numerical scan, exclusion plot, run numerics, validate scan-config, rerun an analysis, replot figures, scan.csv/scan.meta inspection, or custom observable wiring in a HEP phenomenology project.
Numeric execution layer for HEP workspace projects: numerical scans, scan-config validation, constraint decisions, exclusion plots, and analysis summary generation. Use this skill when the user asks for numerical scan, exclusion plot, run numerics, validate scan-config, rerun an analysis, replot figures, scan.csv/scan.meta inspection, or custom observable wiring in a HEP phenomenology project.
HEP Numerics
Use this skill as the numeric execution layer for a structured HEP workspace.
It routes validated model, calculation, and constraint artifacts into scans,
constraint decisions, figures, summaries, and manifest updates.
1. Skill Responsibilities And Boundaries
Responsible: read existing workspace artifacts, validate scan-configs, run numeric scans, evaluate constraints, make figures, write summaries, and update numerics manifest entries.
Responsible: preserve reproducibility through scan.csv, scan.meta.json, deterministic figure names, and manifest history.
Responsible: distinguish hard failures from skipped evaluations and skipped
figures without publishing an incomplete scan as a successful result.
Not responsible: inventing physics, changing model assumptions, changing experimental data, or deciding whether a model is publishable.
Not responsible: symbolic derivations, Feynman rules, loop reductions, or Package-X work.
Not responsible: silently editing model/, constraints/, or calculations/ to make a scan pass.
Not responsible: replacing schema, script, or test checks with prose-only judgment.
Skip Step 1 and Step 3; Step 2 verifies the immutable scan pair/frozen execution snapshot and builds separate renderer provenance
numerics_figures_regenerated
Branch rules:
Branch I creates or completes the scan-config, validates it, runs the scan, makes figures, writes summary, and updates manifest.
Branch II reuses the existing scan-config but reruns validation, scan, figures, summary, and manifest update.
Branch III must reuse an existing strictly verified scan.csv and
scan.meta.json. Its live execution projection must match the stored
snapshot. Title/prose and parallelism-hint drift may be rendered under a
new figures.meta.json; scientific figure/config drift requires a new scan.
It may update figures, figure provenance, summary, and manifest only.
If the user asks to change model, constraints, or calculations, stop and route that work outside this skill.
5. Hard Gates
Validate before scan: validate_scan_config.py must pass before run_scan.py.
Abort before scan-results: hard preflight failure must not create or refresh numerics/scan-results/{analysis_id}/.
Replot does not scan: Branch III must not call run_scan.py.
Do not mutate upstream: never edit model/, constraints/, or calculations/ to satisfy numerics validation.
Do not invent dependencies: stale or missing depends_on entries are hard blockers unless the user asks for a new config.
Recompute and verify dependencies: matching version/checksum strings are not
proof. The model hash, every task calculation graph, the scan CSV hash, and
the complete scan graph must verify from exact current bytes before use.
Do not invent canonical names: unknown machine names are validation errors.
Do not hide skipped work: skipped constraints, observables, or points need
explicit failure diagnostics; skipped figures need explicit recorded reasons.
Fail closed on incomplete point evidence: if any attempted point has an
unavailable/non-finite observable, invalid/non-finite constraint result, or
skipped constraint/verdict, run_scan.py exits nonzero before writing or
refreshing scan.csv, scan.meta.json, the analysis summary, or manifest
history. In-memory skip reasons are diagnostics, not a publishable partial
scan.
Numeric evidence must be a real finite scalar. Booleans, arrays, NaN, and
positive/negative infinity are invalid even when Python can coerce them.
6. Canonical Name Rule
Machine-readable canonical names must match ^[A-Za-z_][A-Za-z0-9_]*$
(ASCII letter or underscore first), must not be a Python hard keyword, and
must reuse the exact
model-spec.json.parameters[].name values; see
docs/contracts/canonical-name-convention.md. Resolve display input only
through parameters[].latex; if no unique existing name matches, stop instead
of inventing an alias. Human labels may use latex, but machine fields,
filenames, CSV columns, figure axes, and custom-observable keyword arguments
use canonical names.
7. Manifest Updates And History Actions
Use scripts for manifest writes whenever possible:
run_scan.py records scan outputs and scan metadata.
make_figures.py records figure outputs and replot-only history.
New history entries MUST include an explicit analysis_id and a fresh
32-character lowercase-hex event_id. The fields are defined by
schemas/manifest.schema.json and documented in
references/scan-results-contract.md
under "Manifest History Entry Fields (Cross-Reference)". Consumers may parse
one exact analysis_id=<id> note token or accept a missing event ID only when
reading legacy history; current producers never use those compatibility paths.
Manifest rules:
Require manifest_version = 2. artifacts.numerics.analyses contains
analysis-owned objects, never string IDs. Each object owns its exact files,
dependency snapshot, producer, timestamp, and status; the aggregate is only
the deterministic projection defined by
docs/contracts/numerics-manifest-ownership.md.
Merge one analysis without rewriting unrelated analysis entries. The only
permitted unrelated-field transition is done/partial to stale after an
exact recorded dependency drifts; stale evidence must still pass intrinsic
scan-pair and graph structure/coverage validation.
Manifest artifact paths must match files that exist on disk.
A full or rerun analysis should point to the scan-config, scan-results, figures, and summary.
A replot-only update must not claim a new scan was run.
status and history actions are declarations, not evidence. Publish done
only after all configured scan/summary/figure evidence and verified graphs
pass their mechanical validators.
Do not add new history action names without updating schemas, scripts, tests, and references.
Build the candidate with build_manifest_for_numerics; do not directly write
through a legacy updater. run_scan.py / make_figures.py publish scan or
figure candidates and the manifest in one shared transaction, manifest last.
The shared serializer rejects paths outside private transaction staging.
If a command reports an incomplete publication journal, inspect it with
python3 scripts/recover_publication_transactions.py --project-dir <project> --format json; use --recover only after reviewing the typed outcome.
8. Common Script Commands
Run commands from the repository root unless the user gives another root.
python3 <skill_dir>/scripts/init_analysis.py --project-dir <project> (allocate a new owned ID)
python3 <skill_dir>/scripts/init_analysis.py --project-dir <project> --allow-formula-fallback (explicitly opt a new draft into detected formula-fallback task backends)
python3 <skill_dir>/scripts/init_analysis.py --project-dir <project> --reuse-draft (explicitly open the newest unexecuted initializer draft)
Reject ambient RNG/entropy; stochastic callables must accept the local rng.
Reject formula fallback task backends unless the scan-config explicitly sets
allow_formula_fallback: true.
Script:
scripts/validate_scan_config.py
references/scan-config-json-contract.md
Outputs:
Validation pass/fail and warnings.
Hard fail:
Validation reports errors.
Dependency, schema, canonical-name, or implementation checks fail.
Step 3 — Run Scan
Inputs:
Validated scan-config
Calculation backends
Custom observables if declared
Do:
Execute the parameter grid.
Derive independent local PCG64 smoke/scan, point, and consumer substreams
from the required seed; never seed global state.
Build the complete exact-byte scan dependency graph before execution and
reverify the same expected coverage immediately before publication.
Compute observable columns.
Evaluate each configured constraint.
Retain diagnostic skip/failure reasons in memory while evaluating all points.
Before any output or manifest mutation, require every attempted point to have
finite observable evidence and a complete allowed or excluded status.
Script:
scripts/run_scan.py
references/constraint-evaluation.md
references/custom-observables-guide.md
Outputs:
numerics/scan-results/{analysis_id}/scan.csv
numerics/scan-results/{analysis_id}/scan.meta.json
Hard fail:
Branch III selected.
Config was not validated first.
Required observable code raises a hard blocker.
Any attempted point or configured constraint is skipped, unavailable,
malformed, boolean-valued, or non-finite. The failed run publishes no scan
pair, summary, or manifest history.
Any input graph drift between preflight and publication.
Step 4 — Make Figures
Inputs:
scan.csv
scan.meta.json
scan-config figure specs
model/model-spec.json
Do:
Render every supported figure spec.
Verify the strict scan pair, its CSV checksum, exact source/snapshot, frozen
execution projection, and scan graph before loading rows or writing a figure.
Build figures.meta.json over the live rendering request, immutable scan
hashes, exact outputs, renderer/helpers, schemas, model, and constraints.
Use canonical names for file names and data lookup.
Use labels and units for human-facing axes.
For every figure, select exactly one slice by requiring figures[].fixed to
name every hidden scan axis and no other axis. Match fixed values by exact
numeric equality; do not use nearest/isclose matching.
Reject duplicate coordinates on the selected slice. Do not aggregate,
median-reduce, choose a first row, or drop duplicates.
Continue past per-figure skips only when the reason is recorded.
Script:
scripts/make_figures.py
references/figure-styles.md
Outputs:
numerics/figures/{analysis_id}/*.pdf
numerics/figures/{analysis_id}/*.png
numerics/figures/{analysis_id}/figures.meta.json
Hard fail:
Required scan result files are missing.
A figure requests unknown axes, observables, or constraint columns.
Step 5 — Write Analysis Summary
Inputs:
scan-config
scan.csv
scan.meta.json
figure listing
Do:
Summarize grid size, columns, constraints, warnings, and skips.
List any explicitly allowed formula fallback task backends.
List generated figures and any skipped figures.
Keep physics interpretation separate from mechanical scan status.
Script:
Prefer existing summary behavior in scripts/run_scan.py and scripts/make_figures.py.
Use references/scan-results-contract.md.
Outputs:
numerics/analysis-summary-{analysis_id}.md
Hard fail:
Summary would describe files that do not exist.
Summary hides failed or skipped required outputs.
Step 6 — Update Manifest
Inputs:
New or refreshed numerics outputs
Existing manifest.json
Selected branch
Do:
Upsert only this analysis's ownership object; preserve every unrelated
analysis object and register this scan-config, scan-results, figures, and
summary paths.
Use the branch's allowed history action.
Keep manifest paths relative to the project root.
Script:
scripts/_manifest.py
Manifest writes inside scripts/run_scan.py and scripts/make_figures.py
Outputs:
Updated manifest.json
Hard fail:
Any manifest path points to a missing file.
Any history action is outside the allowed list.
The existing manifest is version 1 or contains string analysis IDs; diagnose
with scripts/migrate_manifest_v2.py and never migrate implicitly.
A retained analysis entry, dependency snapshot, or owned path would be lost.
Step 7 — Self-Check And Deliver
Inputs:
Validation status
Generated files
manifest.json
Warnings and skip reasons
Do:
Run the checklist in Section 11.
Verify branch-specific hard gates.
Report produced paths, warnings, skips, and blockers.
Script:
Use shell checks plus the scripts already run.
Read references only for failed contract questions.
Outputs:
Final concise status.
Hard fail:
Any checklist item required for the selected branch fails.
.agents and .claude skill copies diverge after edits to this skill.
10. Reference Reading Index
Open this reference
When to open it
references/scan-config-json-contract.md
Creating, editing, validating, or reviewing numerics/scan-configs/{analysis_id}.json
Mode is classified as batch, interactive, or interactive-standalone.
Branch is classified as Branch I, Branch II, or Branch III.
Branch III did not call run_scan.py.
analysis_id is known and matches output paths.
scan-config.json exists for the selected analysis.
All machine-readable parameter names are canonical ASCII names.
Canonical identifiers start with a letter/underscore and are not Python
hard keywords.
No upstream model/, constraints/, or calculations/ file was modified.
validate_scan_config.py passed before any scan run.
Hard preflight failures stopped before scan-results were written.
Any point-level failure, skipped verdict, unavailable value, boolean, or
non-finite value caused a nonzero run with no refreshed scan outputs,
summary, or manifest history.
scan.csv exists when the selected branch requires scan results.
scan.csv row and column contracts match the config.
scan.csv has one unique complete Cartesian grid, exact finite cells,
and a matching scan_csv_sha256.
Every configured observable has a complete finite scalar column; a
recorded skip/failure reason was not treated as successful scan output.
Every configured constraint has verdict, margin, chi2, and skip_reason columns.
Every persisted constraint verdict is allowed or excluded; completed
scan output contains no skipped verdict.
scan.meta.json contains an exact scan-config snapshot, reproducibility
source/hash, explicit RNG metadata, and a verified graph whose
independently derived coverage and hashes pass.
Figures exist for each required figure spec or a skip reason is recorded.
figures.meta.json owns exactly the current figure generation and all
scan/renderer/output hashes verify.
Each figure explicitly fixes exactly every hidden scan axis, uses exact
slice equality, and contains no duplicate selected coordinates.
analysis-summary-{analysis_id}.md exists and is nonempty when summary generation is in scope.
manifest.json paths match files on disk.
Manifest history action is one of the three allowed numerics actions.
Custom observable functions used by the config are implemented and smoke-tested.
.claude/skills/hep-numerics/ and .agents/skills/hep-numerics/ remain byte-identical after skill edits.
