Read a published paper (arXiv id / DOI / local PDF) and turn it into workspace artifacts: literature/paper-meta + paper-extract + repro-targets (Setup mode), and model/calc-tasks/constraints/benchmarks (Formalize mode). Trigger when the user says "reproduce", "reproduce paper", "replicate fig", "rebuild paper", "import paper", "build workspace from arxiv", or supplies a paper identifier (arXiv id, DOI, PDF path) and asks to formalize it. Does NOT do the comparison itself — that is `repro-orchestrator` + `compare_to_reference.py`.
Read a published paper (arXiv id / DOI / local PDF) and turn it into workspace artifacts: literature/paper-meta + paper-extract + repro-targets (Setup mode), and model/calc-tasks/constraints/benchmarks (Formalize mode). Trigger when the user says "reproduce", "reproduce paper", "replicate fig", "rebuild paper", "import paper", "build workspace from arxiv", or supplies a paper identifier (arXiv id, DOI, PDF path) and asks to formalize it. Does NOT do the comparison itself — that is `repro-orchestrator` + `compare_to_reference.py`.
HEP Paper Formalizer
Turn a published paper into the workspace artifacts needed for paper-anchored
reproduction. This skill has two independent modes: Setup mode authors the
literature/ inputs, and Formalize mode reads literature/paper-extract.json
to author model/, constraints/, and model/benchmarks.json. Both modes write
only private foundation candidates and require mechanical finalization before
their outputs become authoritative.
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 skeleton, allocate a Setup candidate, then author the literature files
Missing paper identifier; request to write calculation outputs; no user decision on target subset when target selection is ambiguous
Convert a completed paper extract into model/, constraints/, and benchmark artifacts
Allocate a Formalize candidate, then read its seeded extract and author model/constraint files
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:
Machine-readable canonical names must match ^[A-Za-z_][A-Za-z0-9_]*$,
must not be Python hard keywords, and must reuse exact
model/model-spec.json names once formalization exists; see
docs/contracts/canonical-name-convention.md.
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/.
Before authoring a mode, allocate exactly one private candidate with
scripts/init_foundation_attempt.py --owner hep-paper-formalize. Use mode
setup for Setup and formalize for Formalize. Write only below its returned
candidate_dir; never edit live foundation artifacts or manifest.json.
Setup+Formalize uses two attempts: successfully finalize Setup, allocate a
new Formalize attempt from that authoritative state, then finalize Formalize.
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
Step 0 Confirm / create the project skeleton and allocate a Setup attempt
If workspace/projects/<name>/ does not exist or is empty:
- Call scripts/init_paper_project_skeleton.py relative to the current
skill installation. It creates 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 authors the
initial candidate 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
From the repository root, allocate and retain the exact JSON result:
python scripts/init_foundation_attempt.py \
--project-dir workspace/projects/<name> \
--owner hep-paper-formalize --mode setup --format json
Every path in Steps 2-9 is relative to the returned candidate_dir.
Do not continue if allocation fails, and never reconstruct its token.
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[]** (matches the Forbidden Outputs section below):
- 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 the Forbidden Outputs section)
- 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
paper_local_to_canonical back into paper-extract.json:
{"paper_local_to_canonical": {"MEG bound 2016": "c-001", ...}}
- Draft constraint references in repro-targets.json use paper-local
labels. Formalize mode replaces them with canonical IDs; the
paper_local_to_canonical mapping preserves the original labels for audit.
Step 4 Scan the paper and list reproducible candidate targets:
all figures / tables / key numerical results / analytic formulas
Step 5 *** Intermediate user confirmation ***
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)
- benchmark_point means exactly one reference row; use
keyed_benchmark_set for two or more keyed benchmark rows
- Every keyed numeric target declares explicit match_columns containing
the required axes and disjoint from observables; never infer a reduced
key from columns that happen to be shared by two CSV files
- figure_curve declares its complete comparison_domain and uses only
curve_representation=single_valued_y_of_x; do not encode a parametric
or multi-valued curve as this kind
- parametric_curve declares one path parameter and complete parameter
domain, ordered_parametric_xy representation, open/closed topology,
and exact coordinate scales; it uses normalized symmetric continuous-
polyline geometry and never projects another varying scan axis
- exclusion_region declares coordinate scales and one authoritative
boundary mode, including component/order/open-closed metadata and an
excluded-side probe; disconnected/holed targets declare every closed
reference face with unique ID, immediate parent, interior/exterior
excluded side, and authoritative excluded probe; never infer a
boundary or missing face semantics from raw scan coordinates
- every non-formula target declares scan_parameters, an exact fixed
slice for all hidden scan axes, and canonical normalization metadata
- tolerance and coverage policy are predeclared and never adjusted after
comparison output is seen
Step 7 Create auditable reference evidence for every selected target
For each formula target:
- Write a nonempty structured JSON record conforming to
schemas/formula-reference.schema.json
- Bind paper_id, target_id, expression, source_locator, and acquired_at
For each numeric target:
- Ask the user for the paper/author/supplemental digitized data, or use
an interactive digitization workflow and record its source locator
- Preserve the imported/digitized values in a distinct immutable raw CSV
- Write a distinct canonical-unit CSV for comparison
- Write a third JSON normalization record conforming to
schemas/normalization-record.schema.json; bind both paths and hashes,
source/canonical units, exact finite factor/offset per column,
fixed-parameter conversion metadata, and acquisition provenance
- Do not overwrite the raw file, inject fixed scan columns into it,
guess units in the comparator, or source evidence from generated
numerics/reproduction artifacts
Step 8 Write literature/repro-summary.md (describes input intent, not results)
Step 9 Write / update candidate 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" is allowed by schemas/manifest.schema.json)
* 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
Step 10 Finalize the exact Setup attempt:
python scripts/finalize_foundation_attempt.py \
--project-dir workspace/projects/<name> \
--attempt-dir <returned-attempt-dir> \
--attempt-id <returned-attempt-id> \
--owner hep-paper-formalize --mode setup --format json
Never copy the candidate into the project yourself. Only `published`
or verified `already_published` is authoritative success.
Setup mode candidate output paths:
literature/paper-meta.json
literature/paper-extract.json
literature/repro-targets.json
literature/digitized/ scaffolding and, for each selected numeric target,
distinct raw CSV, canonical-unit CSV, and normalization-record JSON evidence
structured formula-reference JSON evidence for each selected formula target
literature/style/paper-style.mplstyle only when the user asks for a style template
literature/repro-summary.md
candidate manifest.json literature entries only as specified by Step 9;
the finalizer publishes it last
3. Formalize Mode
Author the project-native model, calculation task, constraint, and benchmark
candidate from the paper extract, then publish it through the finalizer.
Step 0 Allocate a fresh Formalize attempt from the authoritative Setup state:
python scripts/init_foundation_attempt.py \
--project-dir workspace/projects/<name> \
--owner hep-paper-formalize --mode formalize --format json
Every path below is relative to the returned candidate_dir.
Step 1 Read candidate 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 paper_local_to_canonical 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 original labels in
paper-extract.json's paper_local_to_canonical mapping
Step 5 Write model/benchmarks.json (paper formulas as benchmarks, has_benchmark=true,
source_type: "literature")
Step 6 Write candidate manifest.json: active_model_version = "v1"
artifacts.model/.constraints.produced_by = "hep-paper-formalize"
artifacts.idea.status = "skipped" (allowed by schemas/manifest.schema.json)
history: model_complete_v1, constraints_complete
Step 7 Finalize the exact Formalize attempt with
scripts/finalize_foundation_attempt.py, passing the returned project,
attempt_dir, attempt_id, owner hep-paper-formalize, mode formalize, and
--format json. Do not report success unless it returns `published` or
verified `already_published`.
Formalize mode candidate 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
candidate manifest.json model and constraint entries only as specified by
Step 6; the finalizer publishes it last
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
schemas/formula-reference.schema.json: formula comparison-evidence schema
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
repository scripts/init_foundation_attempt.py: allocates and seeds the
private owner/mode-bound candidate
repository scripts/finalize_foundation_attempt.py: validates and
transactionally publishes the candidate with manifest.json last
7. Final Delivery Self-Check Checklist
Mode is classified as setup-only, formalize-only, or setup+formalize.
Each executed mode has its own exact foundation allocation tuple; every
generated path is below its returned candidate_dir.
Canonical names satisfy the hard rule above across repro-targets, model,
constraints, and benchmarks.
Every scan_table target has explicit, unique match_columns containing
x_param and y_param and not overlapping observables.
Every benchmark_point target has exactly one reference row; multi-row
benchmark evidence uses keyed_benchmark_set with unique keys.
Every figure_curve target declares and fully covers its predeclared
domain and is finite, duplicate-free, and single-valued.
Every parametric_curve target declares and fully covers its path-
parameter domain, uses ordered finite nodes, fixes every other scan axis,
and declares open/closed topology plus exact coordinate scales.
Every exclusion_region target declares coordinate normalization,
authoritative boundary construction, topology metadata, and an
excluded-side probe; disconnected/holed targets completely declare every
face's parent, side, and probe; raw scan points are not used as a boundary fallback.
Every higher-dimensional target comparison fixes all hidden scan
parameters to one exact declared slice; no aggregation or nearest-match
slice is used.
Every formula target has structured, nonempty formula-reference evidence
bound to the paper and target.
Every numeric target has separate raw, canonical-unit, and normalization
record files; the record binds hashes, units, conversions, and acquisition
provenance.
Tolerances, comparison domains, coverage rules, and unit conversions were
chosen before comparison results were inspected.
HRP-compliant formula handling is preserved: excerpting is allowed, OCR backends are forbidden.
Excerpted formulas include source_anchor and
human_review_required: true.
Setup candidate paths are only under literature/, plus candidate
manifest and the permitted live directory skeleton.
Formalize candidate paths are only under model/ and constraints/,
plus the permitted candidate literature mappings and manifest.
The exact finalizer returned published or verified
already_published; no candidate was copied to live paths manually.
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.
