FESADev/.codex/skills/fesa-reference-comparison/SKILL.md

name, description

name	description
fesa-reference-comparison	Use when comparing FESA solver HDF5 results against Abaqus reference CSV files for reference comparison, checking 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
• Abaqus reference CSV files under reference/<model-id>/
• Optional deterministic solver CSV views materialized from results.h5 for debugging or review

Workflow

1. Follow ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT.
2. ARTIFACT CHECK: verify metadata.json, model.inp, generated solver results.h5, reference/<model-id>/<model-id>_displacements.csv, reference/<model-id>/<model-id>_reactions.csv, reference/<model-id>/<model-id>_internalforces.csv, reference/<model-id>/<model-id>_stresses.csv, reference CSV schema version, FESA HDF5 schema version, units, coordinate system, step/frame identity, ID matching, output location, component naming, and tolerance policy.
3. Stop with needs-reference-artifacts, needs-solver-results, or needs-upstream-decision when required comparison inputs are missing.
4. COMPARE FESA HDF5 datasets by normalizing their rows and matching them directly against Abaqus reference CSV rows.
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 or modify Abaqus reference CSV files.
• 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.
• FESA solver results.h5 is the authoritative solver output.
• Abaqus reference CSV files are the authoritative reference result artifacts.
• FESA debug CSV views are derived from results.h5 for review only; do not treat FESA debug CSV views as authoritative solver output or reference artifacts.

Handoff

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