FESADev/.codex/skills/fesa-numerical-review/SKILL.md

name, description

name	description
fesa-numerical-review	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
• Coordinator Agent dispatch package for the numerical/reference gate

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.
• Both canonical reports must return output paths, status, evidence summary, and blockers before the gate can pass.

Handoff

Return docs/<feature-id>/numerical-review.md and docs/<feature-id>/reference-model.md, status, evidence summary, and blockers to Coordinator Agent. Route both passed reports to I/O Definition Agent, math defects to Formulation Agent, and source gaps to Research Agent through Coordinator Agent.