# Hep Numerics

> >

- **Type:** Skill
- **Install:** `agentstack add skill-huangzhonglv-hep-workflow-hep-numerics`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [huangzhonglv](https://agentstack.voostack.com/s/huangzhonglv)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [huangzhonglv](https://github.com/huangzhonglv)
- **Source:** https://github.com/huangzhonglv/hep-workflow/tree/main/.claude/skills/hep-numerics

## Install

```sh
agentstack add skill-huangzhonglv-hep-workflow-hep-numerics
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 points, skipped constraints, and skipped figures.
- 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.

## 2. Workspace Inputs And Outputs

Read these workspace inputs when present:

- `manifest.json`
- `model/model-spec.json`
- `model/calc-tasks.json`
- `constraints/constraints-data.json`
- `calculations/task-*/result-meta.json`
- `calculations/task-*/result-python.py`
- `numerics/scan-configs/{analysis_id}.json`
- `numerics/custom_observables.py`

Write only these workspace outputs:

- `numerics/scan-configs/{analysis_id}.json`
- `numerics/scan-results/{analysis_id}/scan.csv`
- `numerics/scan-results/{analysis_id}/scan.meta.json`
- `numerics/figures/{analysis_id}/*.{pdf,png}`
- `numerics/analysis-summary-{analysis_id}.md`
- `manifest.json` numerics artifact entries and allowed history actions

Treat `model/`, `constraints/`, and `calculations/` inputs as read-only.

## 3. Mode Classification

Classify the mode before reading or writing numerics outputs.

| Mode | Required signals | Use when | First action |
| --- | --- | --- | --- |
| `batch` | Workspace root, `manifest.json`, `numerics/`, explicit `analysis_id` | User or orchestrator names an existing or desired analysis | Load the named scan-config or initialize it if Branch I needs one |
| `interactive` | Workspace root, `manifest.json`, `numerics/`, missing or unclear `analysis_id` | User describes scan intent but has not fixed the config | Determine `analysis_id`, then create or edit the scan-config |
| `interactive-standalone` | No complete workspace skeleton | User asks for numerics outside a workspace | Ask for or create the minimum workspace layout before running scripts |

Hard rules:

- Prefer `batch` whenever the project root and `analysis_id` are explicit.
- Prefer `interactive` over guessing when more than one scan-config could match.
- Use `interactive-standalone` only as a fallback; scans still require structured equivalents of the workspace inputs.
- Ask at most one concise clarification when mode or `analysis_id` cannot be inferred safely.

## 4. Branch Classification

Choose the branch from user intent after mode classification.

| Branch | Trigger wording examples | Skip which Step | History action |
| --- | --- | --- | --- |
| Branch I full analysis | "run a new analysis", "scan this project", "make a scan-config and run" | None | `numerics_analysis_complete` |
| Branch II rerun | "rerun analysis-001", "same config, refresh scan", "rerun scan" | Skip Step 1 only when config already exists | `numerics_analysis_rerun` |
| Branch III replot-only | "replot", "make figures again", "change figure style" | Skip Step 1, Step 2 scan preflight only if existing results already pass, and Step 3 | `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 existing `scan.csv` and `scan.meta.json`; it may update figures, 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.
- Do not invent canonical names: unknown machine names are validation errors.
- Do not hide skipped work: skipped constraints, observables, points, or figures need explicit reasons in outputs.

## 6. Canonical Name Rule

Machine-readable names must be ASCII canonical names from `model/model-spec.json`.

- Canonical source: `model-spec.json.parameters[].name`.
- Display source: `model-spec.json.parameters[].latex`.
- Required in scan-config: `scan_parameters[].name`, `fixed_parameters[].name`, observable parameter references, constraint parameter references, figure axes, and custom observable keyword arguments.
- Forbidden in machine fields: LaTeX, Unicode symbols, primes, subscripts, superscripts, spaces, and display labels.
- Conversion flow:
  - Read `model-spec.json.parameters[]`.
  - Build a lookup from canonical `name` and known `latex` display labels.
  - Convert user-provided display text to the existing canonical `name`.
  - If multiple canonical names match, ask before writing.
  - If no canonical name matches, reject the config field instead of inventing an alias.
- Keep labels for humans only: axis labels and figure legends may use `latex`, but filenames and CSV columns use canonical names.
- Preserve canonical names in custom observables; function parameters must match the canonical keyword arguments used by `run_scan.py`.

## 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.
- `scripts/_manifest.py` contains shared manifest helpers.

Allowed history actions for this skill:

- `numerics_analysis_complete`
- `numerics_analysis_rerun`
- `numerics_figures_regenerated`

History entries MAY include an optional `analysis_id` field to associate them with a specific numerics analysis. The field is defined by `schemas/manifest.schema.json` and documented in [`references/scan-results-contract.md`](references/scan-results-contract.md) under "Manifest History Entry Fields (Cross-Reference)". Consumers fall back to parsing `analysis_id=` from the `note` string when the field is absent, so producers may use either form.

Manifest rules:

- 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.
- Do not add new history action names without updating schemas, scripts, tests, and references.

## 8. Common Script Commands

Run commands from the repository root unless the user gives another root.

- `python3 /scripts/init_analysis.py --project-dir  --analysis-id `
- `python3 /scripts/validate_scan_config.py --project-dir  --analysis-id `
- `python3 /scripts/run_scan.py --project-dir  --analysis-id `
- `python3 /scripts/make_figures.py --project-dir  --analysis-id `

Use the installed skill directory for ``, such as `.claude/skills/hep-numerics` or `.agents/skills/hep-numerics`.

## 9. Step 0–7 Execution Route

### Step 0 — Classify Mode And Branch

Inputs:
- User request
- Current working directory
- `manifest.json`
- `numerics/`
Do:
- Identify workspace root.
- Determine `analysis_id`.
- Select `batch`, `interactive`, or `interactive-standalone`.
- Select Branch I, II, or III.
Script:
- Use filesystem checks; no required script.
Outputs:
- Mode, branch, project directory, and `analysis_id`.
Hard fail:
- No safe workspace or standalone equivalent exists.
- Branch III requested without existing scan results.

### Step 1 — Create Or Load Scan Config

Inputs:
- `manifest.json`
- `model/model-spec.json`
- `constraints/constraints-data.json`
- Existing `numerics/scan-configs/{analysis_id}.json`
Do:
- Load existing config for Branch II or III.
- Create a draft config for Branch I when missing.
- Resolve all parameter display labels to canonical names.
- Add only declared observables, constraints, and figure specs.
Script:
- `scripts/init_analysis.py`
- `references/scan-config-json-contract.md`
Outputs:
- `numerics/scan-configs/{analysis_id}.json`
Hard fail:
- Required upstream artifacts are missing.
- Any machine field cannot be resolved to a canonical name.

### Step 2 — Validate Config And Dependencies

Inputs:
- `numerics/scan-configs/{analysis_id}.json`
- `model/`
- `constraints/`
- `calculations/`
Do:
- Run schema and semantic validation.
- Check `depends_on` versions, checksums, and task ids.
- Check scan/fixed parameter conflicts.
- Check observable and constraint implementation readiness.
- 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.
- Compute observable columns.
- Evaluate each configured constraint.
- Record skip reasons instead of dropping rows.
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.

### Step 4 — Make Figures

Inputs:
- `scan.csv`
- `scan.meta.json`
- scan-config figure specs
- `model/model-spec.json`
Do:
- Render every supported figure spec.
- Use canonical names for file names and data lookup.
- Use labels and units for human-facing axes.
- 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`
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:
- Register 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.

### 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` |
| `references/scan-results-contract.md` | Inspecting `scan.csv`, `scan.meta.json`, row counts, column order, metadata, warnings, or rerun reproducibility |
| `references/constraint-evaluation.md` | Debugging verdicts, margins, chi2, skip reasons, direct limits, interpolated limits, or manual-only constraints |
| `references/figure-styles.md` | Making or reviewing `exclusion_2d` or `scan_1d` figures, labels, filenames, color policy, or replot behavior |
| `references/custom-observables-guide.md` | Wiring custom observables, parameter-combination fallbacks, custom signatures, smoke tests, or `NotImplementedError` blockers |

## 11. Final Delivery Self-Check Checklist

- [ ] 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.
- [ ] 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.
- [ ] `scan.csv` exists when the selected branch requires scan results.
- [ ] `scan.csv` row and column contracts match the config.
- [ ] Every configured observable has a column or a recorded skip/failure reason.
- [ ] Every configured constraint has `verdict`, `margin`, `chi2`, and `skip_reason` columns.
- [ ] `scan.meta.json` contains the scan-config snapshot and reproducibility metadata.
- [ ] Figures exist for each required figure spec or a skip reason is recorded.
- [ ] `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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [huangzhonglv](https://github.com/huangzhonglv)
- **Source:** [huangzhonglv/hep-workflow](https://github.com/huangzhonglv/hep-workflow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-huangzhonglv-hep-workflow-hep-numerics
- Seller: https://agentstack.voostack.com/s/huangzhonglv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.