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

name, description

name	description
fesa-reference-comparison	Use when comparing FESA results.h5 quantities against feature-declared Abaqus CSV values or diagnosing reference tolerance, identity, row-set, or nonfinite-result failures.

FESA Reference Comparison

Compare generated FESA HDF5 values with only the Abaqus CSV quantities declared by the feature. The comparison tests observable values; it does not test Abaqus implementation equivalence.

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 FESA results.h5
• Declared reference .inp and required Abaqus CSV files

Workflow

1. Follow ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT.
2. ARTIFACT CHECK: verify the declared input, results.h5, every required CSV, HDF5 projection, source-ID/component mapping, row prechecks, blocking/warning behavior, and tolerance.
3. Reject a missing input or required CSV as needs-reference-artifacts.
4. Reject a missing HDF5 result or comparison command as needs-solver-results.
5. Reject missing, extra, duplicate, or nonfinite required rows before tolerance evaluation.
6. COMPARE: normalize HDF5 values and match CSV values by declared source identity and component. Never match by row order alone.
7. Apply the upstream tolerance exactly. Do not clamp values, drop rows, loosen tolerance, or modify either artifact to obtain a pass.
8. Report per-row decisions, max absolute error, max relative error, RMS error, norm error when required, worst source ID/component, and pass/fail or warning per quantity.
9. CLASSIFY failures as missing-reference-artifact, missing-solver-output, schema-mismatch, id-mismatch, tolerance-failure, nonfinite-result, upstream-contract, or environment.

Do not require canonical names, README, metadata, Abaqus version/provenance, duplicated CSV units/coordinates/step-frame fields, or a reference CSV schema version unless the feature requirements explicitly make one of them part of comparison acceptance.

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, tests, CMake, upstream contracts, reference artifacts, or tolerances.
• Do not run Abaqus, Nastran, or another reference solver.
• Do not generate or modify reference CSV files.
• Do not approve physics validation or release readiness.

Quality Gate

• Every declared required row has a deterministic source-ID/component match.
• Missing/extra/duplicate/nonfinite required rows remain visible and fail before tolerance.
• Warning-only quantities never change the blocking pass/fail verdict.
• pass-for-physics-evaluation means required reference tolerance success only.
• FESA results.h5 remains authoritative solver output; Abaqus CSV remains external reference data.

Handoff

Send passing reports to Physics Evaluation Agent. Send implementation-owned mismatches to Correction Agent, missing declared files to Reference Model Agent, and HDF5 projection or identity-contract conflicts to I/O Definition Agent.