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

name, description

name	description
fesa-reference-models	Use when designing FESA reference model portfolios, Abaqus input artifact bundles, metadata provenance, required Abaqus reference CSV files, coverage matrices, and implementation-planning handoffs.

FESA Reference Models

Use this skill to define test model portfolios and reference artifact contracts before implementation planning.

Inputs

Read these first:

• AGENTS.md
• docs/SOLVER_AGENT_DESIGN.md
• docs/reference-models/README.md
• docs/requirements/<feature-id>.md
• docs/research/<feature-id>-research.md
• docs/formulations/<feature-id>-formulation.md
• docs/numerical-reviews/<feature-id>-review.md
• docs/io-definitions/<feature-id>-io.md

Workflow

1. Define reference strategy: code verification, solution verification, and benchmark/reference comparison.
2. Build a model inventory: smoke, analytical, patch test, benchmark, regression, and negative/invalid-input models.
3. For each model, record model_id, purpose, verified requirements, analysis type, element type, material, boundary conditions, loads, expected quantities, tolerance, source, and status.
4. Define reference/<model-id>/ artifact bundle requirements.
5. Require model.inp, the applicable <model-id>_displacements.csv, <model-id>_reactions.csv, <model-id>_internalforces.csv, <model-id>_stresses.csv, and README.md unless explicitly not applicable. Treat metadata.json as optional.
6. Define optional <model-id>_strains.csv, <model-id>_energy_or_residual.csv, and <model-id>_<quantity>.csv only when upstream acceptance criteria require them.
7. Define metadata provenance, units, coordinate system, output requests, artifact status, reference_csv_schema_version, reference_csv_files, and limitations in the Reference Model Contract. If metadata.json exists, inventory it read-only and cross-check overlapping fields.
8. Build a Coverage Matrix mapping requirement id, model id, compared quantity, FESA HDF5 dataset, reference CSV file, tolerance, verification method, and status.

Output Contract

Produce or revise docs/reference-models/<feature-id>-reference-models.md with:

• Metadata
• Reference Strategy
• Model Inventory
• Model Record
• Abaqus Input Requirements
• Artifact Bundle Contract
• Reference Metadata Contract and optional metadata.json cross-check
• Abaqus Reference CSV Requirements
• Coverage Matrix
• Artifact Acceptance Checklist
• Open Issues and Downstream Handoff

Boundaries

• Do not implement code.
• Do not implement parsers.
• Do not design C++ APIs or file ownership.
• Do not run Abaqus, Nastran, or any reference solver.
• Do not generate or modify Abaqus reference CSV files.
• Do not compare solver results.
• Do not approve release readiness.

Quality Gate

• Every must requirement maps to at least one model and compared quantity.
• model.inp stays within the supported Abaqus keyword subset or records an open issue.
• The Reference Model Contract includes provenance, Abaqus version/source, units, coordinate system, tolerance, reference_csv_schema_version, and reference_csv_files.
• An absent metadata.json is allowed and does not change readiness. A present file is read-only supplementary evidence; any conflict with the contract or stored artifacts remains visible as an upstream issue.
• Missing required Abaqus reference CSV files keep the model at needs-reference-artifacts.

Handoff

Send model order and tests that should fail first to Implementation Planning Agent. Send FESA HDF5 dataset paths, reference CSV schemas, matching, output location, and tolerance mapping to Reference Verification Agent. Send physical expectations to Physics Evaluation Agent.