# Hep Paper Formalize

> >

- **Type:** Skill
- **Install:** `agentstack add skill-huangzhonglv-hep-workflow-hep-paper-formalize`
- **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-paper-formalize

## Install

```sh
agentstack add skill-huangzhonglv-hep-workflow-hep-paper-formalize
```

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

## About

# HEP Paper Formalizer

Turn a published paper into the workspace artifacts needed for paper-anchored
reproduction. This skill has two independent modes: **Setup mode** writes the
`literature/` inputs, and **Formalize mode** reads `literature/paper-extract.json`
to write `model/`, `constraints/`, and `model/benchmarks.json`.

This skill operates under `docs/contracts/honest-reproduction-principle.md`.
Paper formulas, curves, tables, and benchmark numbers are comparison targets
only. They must not become computational backends for Package-X, Python
translation, scans, or reproduction verdicts.

Mode selection is normally made by `repro-orchestrator` from
`manifest.artifacts.model.status`: a paper-first project runs Setup then
Formalize; a project that already has a model can run Setup only; a project
with existing `literature/paper-extract.json` can run Formalize only.

## 1. Mode Classification

Classify the mode before reading or writing artifacts.

| Mode | Inputs | Use when | First action | Hard fails |
| --- | --- | --- | --- | --- |
| `setup-only` | Paper identifier or PDF path; project name or existing project directory | Add `literature/` artifacts to a project whose model already exists, or prepare comparison targets before later formalization | Locate or initialize the project skeleton, then write `literature/paper-meta.json`, `literature/paper-extract.json`, `literature/repro-targets.json`, and `literature/repro-summary.md` | Missing paper identifier; request to write calculation outputs; no user decision on target subset when target selection is ambiguous |
| `formalize-only` | Existing `literature/paper-extract.json`; project directory | Convert a completed paper extract into `model/`, `constraints/`, and benchmark artifacts | Read `paper-extract.json`, then write model and constraint artifacts using canonical names | Missing paper extract; extracted formulas requested as calculation backend; request to fetch latest external constraints instead of using the paper |
| `setup+formalize` | Paper identifier or PDF path; project name or empty project directory | Build a paper-first workspace from scratch | Run Setup mode through user target confirmation, then continue into Formalize mode | Any Setup hard fail; user declines target set; unresolved canonical naming conflicts |

Hard rules:

- Use canonical ASCII names for every machine-readable parameter name.
- `literature/` is an input bucket for reproduction; `reproduction/` is not
  written by this skill except directory skeleton creation.
- Do not modify `calculations/`, `numerics/scan-configs/`, or
  `reproduction/runs/`.
- If the user asks to compare against scan outputs, stop after writing the
  inputs and route the comparison to `repro-orchestrator` +
  `scripts/compare_to_reference.py`.

## 2. Setup Mode

Write `literature/` artifacts that describe what the paper says and what the
project should later reproduce.

Use these local references when authoring JSON:

- `references/paper-meta-contract.md`
- `references/paper-extract-contract.md`
- `references/repro-targets-contract.md`

```text
Step 0  Confirm / create the project skeleton
        If workspace/projects// does not exist or is empty:
          - Call .claude/skills/hep-paper-formalize/scripts/init_paper_project_skeleton.py
            (newly written, following the pattern of hep-idea/scripts/init_project_skeleton.py,
             and additionally creating literature/, literature/digitized/, literature/style/,
             reproduction/, reproduction/runs/, reproduction/figures/,
             reproduction/reports/, and related directories)
          - manifest.json does not exist at this point; Setup mode writes the initial version in Step 9
        If the project already has manifest.json:
          - Read it and confirm fields such as active_model_version
          - Step 9 uses update rather than create

Step 1  Receive the paper identifier (arxiv id / DOI / PDF path)
Step 2  Fetch / read the PDF and write literature/paper-meta.json
Step 3  Digest the paper and extract structured middleware → literature/paper-extract.json
        Includes fields[] / parameters[] / interactions[] / constraints_in_paper[]
        / observables[] / formulas[] / scan_config_hints[] / unit_conversion_notes[]

        **Important: write boundary for formulas[]** (mirrors the exclusions in §13):
        - Allowed: the LLM may excerpt formula LaTeX strings explicitly written in the paper
          into formulas[].latex, with source_anchor (section / equation number) and
          human_review_required: true on every entry
        - Forbidden: any downstream skill / script must not treat formulas[] as a computational backend
          (these formulas may only be copied into model/benchmarks.json for after-the-fact validation;
           see §4.6 Forbidden outputs)
        - Forbidden: automatically extracting formulas from rendered PDF images via OCR
          (OCR is unreliable and can introduce incorrect benchmarks)

        **Naming constraint for constraints_in_paper[]** (fixes ID-ordering issues):
        - During Setup, c-001-style canonical constraint IDs do **not** exist yet
          (those IDs are generated when Formalize mode writes constraints-data.json)
        - Therefore this stage may only use paper-local labels, for example:
          {"label": "MEG bound 2016", "source_anchor": "Tab. 2, row 1"}
        - After Formalize mode generates constraints-data.json, it writes back a
          resolved_mapping into paper-extract.json:
          {"MEG bound 2016": "c-001", ...}
        - Constraint references in repro-targets.json targets also use paper-local
          labels; compare_to_reference.py resolves them through resolved_mapping

Step 4  Scan the paper and list reproducible candidate targets:
        all figures / tables / key numerical results / analytic formulas
Step 5  *** Intermediate user confirmation (solution for risk H) ***
        Present the candidate target list to the user and let the user choose:
        "all / specified subset / only fig-3a + tab-2 / defer target selection"
Step 6  Write literature/repro-targets.json (draft) according to the user's choice
        Each target's constraint references use paper-local labels (see the Step 3 notes)
Step 7  For each figure_curve / exclusion_region target, prompt the user:
        "Please provide the digitized CSV, or use WebPlotDigitizer interactively and then tell me the path"
Step 8  Write literature/repro-summary.md (describes input intent, not results)
Step 9  Write / update manifest.json:
        - If the manifest does not exist (paper-first project): create the initial version
            * Set project_name, created, and last_updated to today
            * active_model_version = null (the model has not been written yet)
            * artifacts.idea = {status: "skipped", files: [], produced_by: null,
                                timestamp: null} ("skipped" requires the schema enum extension in §3.2)
            * artifacts.model / calculations / numerics all use empty skeletons
              (same as the initial template in hep-idea manifest-json-contract.md)
            * artifacts.literature = {status: "done", files: [...],
                                      produced_by: "hep-paper-formalize",
                                      timestamp: now}
            * artifacts.reproduction = {status: "not_started", runs: [], ...}
            * history: one entry { action: "literature_complete",
                                    by: "hep-paper-formalize" }
        - If the manifest already exists (adding reproduction to an existing hep-idea project):
            * Only append / update artifacts.literature
            * Add "literature_complete" or "literature_updated" to history
            * Do not touch other artifacts
```

Setup mode output paths:

- `literature/paper-meta.json`
- `literature/paper-extract.json`
- `literature/repro-targets.json`
- `literature/digitized/` scaffolding or user-provided digitized CSV pointers
- `literature/style/paper-style.mplstyle` only when the user asks for a style template
- `literature/repro-summary.md`
- `manifest.json` literature entries only as specified by Step 9

## 3. Formalize Mode

Write the project-native model, calculation task, constraint, and benchmark
artifacts from the paper extract.

```text
Step 1  Read literature/paper-extract.json
Step 2  Write model/model-spec.json according to docs/contracts/canonical-name-convention.md
Step 3  Write model/calc-tasks.json according to the contracts in docs/contracts/
Step 4  Write constraints/constraints-data.json (use the constraint values given by the paper; do not search the web for newer values)
        - Generate c-001, c-002, ... canonical constraint IDs
        - Write resolved_mapping back into literature/paper-extract.json:
          {"paper_local_to_canonical": {"MEG bound 2016": "c-001", ...}}
        - Refresh literature/repro-targets.json in sync: replace paper-local
          labels in targets with canonical IDs (preserve the paper-local label
          as _label_was for audit)
Step 5  Write model/benchmarks.json (paper formulas as benchmarks, has_benchmark=true,
        source_type: "literature")
Step 6  Write manifest.json: active_model_version = "v1"
        artifacts.model/.constraints.produced_by = "hep-paper-formalize"
        artifacts.idea.status = "skipped" (the schema already adds this enum value in §3.2)
        history: model_complete_v1, constraints_complete
```

Formalize mode output paths:

- `model/model-spec.json`
- `model/calc-tasks.json`
- `model/benchmarks.json`
- `constraints/constraints-data.json`
- `constraints/constraints-summary.md` when useful for human review
- `literature/paper-extract.json` only to add `paper_local_to_canonical`
- `literature/repro-targets.json` only to replace paper-local labels with
  canonical constraint IDs while preserving `_label_was`
- `manifest.json` model and constraint entries only as specified by Step 6

Do not search the web for newer constraints during Formalize mode. The point is
to formalize the paper being reproduced, not to update the paper.

## 4. Forbidden Outputs

Source of authority: `docs/contracts/honest-reproduction-principle.md`.

> **Forbidden**: `hep-paper-formalize` MUST NOT write any of the following:
> - `result.wl`, `result-python.py`, `result-meta.json` —— these belong to `package-scribe`
> - `numerics/scan-configs/*` —— these belong to `hep-numerics` or `repro-orchestrator`
> - `reproduction/runs/*` —— these belong to `repro-orchestrator` + `compare_to_reference.py`
>
> **Specifically**: when extracting paper formulas in Formalize mode, write them
> ONLY into `model/benchmarks.json.formula_latex` (existing benchmark slot,
> `source_type: "literature"`). DO NOT translate paper formulas into
> `result-python.py` or supply them as Python "starter code" for package-scribe.
> Package-X derivation is package-scribe's responsibility; supplying paper
> formulas to it short-circuits the independent derivation required by HRP.

- MUST NOT write `result-python.py` / `numerics/scan-configs/*` / `reproduction/runs/*`.
- MUST NOT write `result.wl` or `result-meta.json`.
- MUST NOT OCR formulas from rendered PDF images and promote them to a backend.
- MUST NOT use paper formulas as starter code for Package-X or Python.
- MUST NOT write comparison verdicts, metrics, diagnostic reports, or
  `reproduction-result.json`.

Allowed formula handling:

- LLM may excerpt formulas that are written in the paper text into
  `literature/paper-extract.json.formulas[].latex`.
- Each excerpted formula must include `source_anchor` and
  `human_review_required: true`.
- These formulas may only become benchmarks or report-side comparison text.

## 5. Relationship To hep-idea

- `hep-paper-formalize` and `hep-idea` do not depend on each other and do not
  call each other.
- Both reference `docs/contracts/canonical-name-convention.md` and the shared
  schema contracts.
- Trigger keywords must remain disjoint:
  - hep-idea: "research idea / new project / propose a topic / brainstorm"
  - hep-paper-formalize: "reproduce / reproduce paper / replicate / import paper / arxiv id"
- `hep-idea` Branch II model revision can apply to projects created by
  `hep-paper-formalize`; `produced_by` does not affect revision semantics.

If the user asks for a new research direction, use `hep-idea`. If the user asks
to import, formalize, or reproduce a specific paper, use `hep-paper-formalize`.

## 6. Reference And Template Map

- `references/paper-meta-contract.md`: contract for `literature/paper-meta.json`
- `references/paper-extract-contract.md`: contract for `literature/paper-extract.json`
- `references/repro-targets-contract.md`: contract for `literature/repro-targets.json`
- `templates/paper-meta.example.json`: canonical paper metadata example
- `templates/paper-extract.example.json`: canonical paper extraction example
- `templates/repro-targets.example.json`: canonical reproduction target example
- `templates/paper-style.mplstyle`: optional matplotlib style template copied
  to `literature/style/paper-style.mplstyle`
- `scripts/init_paper_project_skeleton.py`: creates directories only; it does
  not create `manifest.json`

## 7. Final Delivery Self-Check Checklist

- [ ] Mode is classified as `setup-only`, `formalize-only`, or `setup+formalize`.
- [ ] All parameter names satisfy canonical-name compliance: ASCII letters,
      digits, and underscores only.
- [ ] Every machine-readable parameter name used in repro-targets, model,
      constraints, and benchmarks matches `model/model-spec.json` once model
      formalization exists.
- [ ] HRP-compliant formula handling is preserved: excerpting is allowed, OCR backends are forbidden.
- [ ] Excerpted formulas include `source_anchor` and
      `human_review_required: true`.
- [ ] Setup mode output paths are only under `literature/`, plus the permitted
      manifest update and directory skeleton.
- [ ] Formalize mode output paths are only under `model/` and `constraints/`,
      plus the permitted literature mapping updates and manifest update.
- [ ] No `result.wl`, `result-python.py`, `result-meta.json`,
      `numerics/scan-configs/*`, or `reproduction/runs/*` file was written.
- [ ] `constraints_in_paper[]` uses paper-local labels during Setup mode.
- [ ] Formalize mode resolves paper-local constraint labels to `c-NNN` IDs and
      preserves the old labels for audit.
- [ ] `scan_config_hints[].missing_fields[]` records missing L1 inputs rather
      than pretending the paper gives a complete scan definition.
- [ ] `.claude/skills/hep-paper-formalize/` and
      `.agents/skills/hep-paper-formalize/` 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-paper-formalize
- 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%.