---
name: fesa-numerical-review
description: Use when independently reviewing FESA FEM formulation numerical correctness, stability risks, verification readiness, and existing reference-case input/CSV readiness before I/O definition.
---

# FESA Numerical and Reference Review

Use this skill to review a formulation as a numerical algorithm contract and to inventory the
minimum existing reference inputs and CSV quantities required by the approved feature scope before
I/O definition.

## Inputs

Read these first:

- `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/<feature-id>/requirements.md`
- `docs/<feature-id>/research.md`
- `docs/<feature-id>/formulation.md`
- Existing stored reference artifacts under `reference/`, read-only

## Workflow

FORMULATION REVIEW -> REFERENCE CASE INVENTORY -> CLASSIFY -> REPORT -> I/O HANDOFF

1. **FORMULATION REVIEW:** Lead with findings and required revisions. Check dimensions, signs,
   DOF ordering, constrained/free assumptions, coordinate transforms, kinematic operator,
   constitutive contract, Jacobian and derivative rules, integration policy, element residual,
   internal force, external force, stiffness, tangent consistency, symmetry, and positive-definiteness
   expectations, and only the feature-approved stability and verification risks.
2. **REFERENCE CASE INVENTORY:** List each existing case using its exact directory, input filename,
   and required CSV filenames. Confirm declared input and every required comparison CSV are present
   and readable without renaming, repairing, normalizing, generating, or modifying artifacts.
   Define logical blocking and warning-only quantities, source identity/component matching, row
   prechecks for missing, extra, duplicate, and nonfinite required rows, and the approved tolerance.
3. **CLASSIFY:** Use only `pass-for-io-definition`, `needs-formulation-revision`,
   `needs-research`, `needs-reference-artifacts`, `needs-user-decision`, or `blocked`.
4. **REPORT:** Produce both reports in the Output Contract.
5. **I/O HANDOFF:** Send both reports through Coordinator Agent to I/O Definition Agent. I/O
   Definition owns the final HDF5 dataset projection; this review owns logical quantities and source identity.

## Output Contract

Produce or revise `docs/<feature-id>/numerical-review.md` with:

- Metadata and source formulation
- Review Verdict
- Critical Findings
- Numerical Risk Assessment
- Consistency Checks
- Verification Readiness
- Required Revisions
- Downstream Handoff

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

- Metadata
- Reference Acceptance Scope
- Reference Case Inventory: exact input and required CSV paths
- Source Identity and Component Contract: logical quantity, source identity, component matching,
  and blocking or warning-only classification
- Row Prechecks: missing, extra, duplicate, and nonfinite required rows fail before tolerance
- Tolerance and Blocking/Warning Policy: exact approved tolerance without invention or calibration
- Open Issues and I/O Handoff: logical quantity and source identity information for the I/O contract

## Boundaries

- Do not implement code.
- Do not edit formulations directly.
- Do not design C++ APIs or file ownership.
- Do not run Abaqus, Nastran, or any reference solver.
- Do not generate, rename, repair, normalize, or modify reference inputs or CSV files.
- Do not approve release readiness.
- Do not decide reference comparison success.
- Do not include final HDF5 dataset paths; I/O Definition owns that projection.

## Quality Gate

- `pass-for-io-definition` means both reviews are ready for I/O definition, not that the feature is complete.
- Confirmed defects, risks, open questions, and test recommendations are separated.
- Missing derivations are returned to Formulation Agent instead of being silently fixed.
- Missing theory or benchmark evidence is routed to Research Agent.
- Use `needs-reference-artifacts` only when a declared input or required comparison CSV is missing.
- Use `needs-user-decision` only when a required quantity, source identity/component match,
  tolerance, or supported-keyword policy is undefined.
- Canonical naming, README, metadata, provenance, extended portfolios, and unrequired CSV files do
  not block readiness.

## Handoff

Send both completed reports through Coordinator Agent to I/O Definition Agent. Send math defects to
Formulation Agent, source gaps to Research Agent, and blocked decisions to Coordinator Agent.