---
name: fesa-reference-comparison
description: Use when running FESA solver HDF5 reference comparison with deterministic CSV view checks, checking stored artifacts, schema, units, ID matching, tolerance metrics, and reference verification status.
---

# FESA Reference Comparison

Use this skill to compare generated solver outputs against stored reference artifacts without modifying either side.

## Inputs

Read these first:

- `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/reference-verifications/README.md`
- Build/Test report with `pass-for-reference-verification`
- `docs/reference-models/<feature-id>-reference-models.md`
- `docs/io-definitions/<feature-id>-io.md`
- Generated solver result HDF5, normally `results.h5`
- Deterministic solver CSV views when a comparison command materializes them
- Stored `references/<feature-id>/<model-id>/` artifacts

## Workflow

1. Follow `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`.
2. ARTIFACT CHECK: verify `metadata.json`, required `reference.h5`, generated solver `results.h5`, deterministic CSV view files, schema version, units, coordinate system, step/frame identity, ID matching, output location, component naming, and tolerance source.
3. Stop with `needs-reference-artifacts`, `needs-solver-results`, or `needs-upstream-decision` when required comparison inputs are missing.
4. COMPARE authoritative HDF5 datasets first, using deterministic CSV view files such as `csv/displacements.csv`, `csv/reactions.csv`, `csv/element_forces.csv`, `csv/stresses.csv`, and optional `csv/strains.csv` or `csv/energy_or_residual.csv` only as stable review/comparison views.
5. Apply upstream tolerance exactly. Do not loosen or reinterpret tolerance.
6. Report max absolute error, max relative error, RMS error, norm error, worst id, worst component, missing rows, extra rows, and pass/fail.
7. CLASSIFY failures as missing-reference-artifact, missing-solver-output, schema-mismatch, id-mismatch, unit-or-coordinate-mismatch, tolerance-failure, nonfinite-result, upstream-contract, or environment.

## Output Contract

Produce or revise `docs/reference-verifications/<feature-id>-reference-verification.md` with:

- Metadata
- Artifact Inventory
- Comparison Contract
- Quantity Results
- Failure Classification
- Handoff Recommendation
- No-Change Assertion
- Open Issues

## Boundaries

- Do not edit source code.
- Do not edit tests.
- Do not edit CMake files.
- Do not change requirements, formulations, I/O contracts, reference artifacts, or tolerance policies.
- Do not change tolerance policies.
- Do not run Abaqus, Nastran, or any reference solver.
- Do not generate reference HDF5 files or deterministic CSV views.
- Do not approve physics validation or release readiness.

## Quality Gate

- Every compared row has a deterministic matching rule.
- Missing rows and extra rows are reported, not ignored.
- Nonfinite values are reported explicitly.
- `pass-for-physics-evaluation` means reference tolerance success only.
- Solver `results.h5` and `reference.h5` are authoritative comparison inputs.
- Deterministic CSV view files are derived views only; do not normalize them beyond documented matching and metrics.

## Handoff

Send passing reports to Physics Evaluation Agent. Send implementation-owned mismatches to Correction Agent. Send missing artifacts to Reference Model Agent and HDF5/CSV view schema conflicts to I/O Definition Agent.