FESADev/.codex/skills/fesa-fem-specification/SKILL.md

name, description

name	description
fesa-fem-specification	Use when drafting or reviewing FESA FEM formulations, numerical review criteria, Abaqus .inp keyword subsets, internal model mappings, result CSV schemas, output recovery, numerical risks, or implementation-planning handoffs before C++ implementation or reference validation.

FESA FEM Specification

Overview

Use this skill to convert approved FESA requirements and research briefs into an implementation-ready FEM specification package: mathematical formulation, independent numerical review criteria, and Abaqus .inp/CSV I/O contract.

This skill is shared by Formulation Agent, Numerical Review Agent, I/O Definition Agent, and Implementation Planning Agent. It prepares specifications only; implementation and reference validation are handled by other skills.

Inputs

Read the smallest useful set of these inputs before drafting or reviewing a specification:

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

Workflow

1. INPUT CHECK: verify that requirements, research sources, analysis type, element type, material scope, output quantities, units, coordinate system, and tolerance status are available. Mark missing decisions as needs-user-decision or needs-research.
2. FORMULATION SPEC: draft the math-level contract: strong form, weak/variational form, discretization, shape functions, DOFs, kinematics, constitutive contract, element residual/internal force, stiffness/tangent, mapping/Jacobian, numerical integration, and output recovery.
3. NUMERICAL REVIEW CHECK: review dimensions, signs, DOF ordering, coordinate transforms, matrix/vector sizes, integration weights, tangent consistency, output locations, rigid body modes, patch test readiness, symmetry, positive definiteness, hourglass, locking, distortion, singular Jacobian, conditioning, and convergence expectations.
4. I/O CONTRACT: define the feature-specific Abaqus .inp supported keyword subset, unsupported/ignored/error policy, model data/history data mapping, internal semantic model mapping, output request mapping, and result CSV schema.
5. HANDOFF: pass math-level pseudocode, parser acceptance cases, CSV writer tests, numerical risk tests, and open issues to Implementation Planning Agent without prescribing C++ structure.

Output Contract

Create or review one or more of these documents:

• docs/formulations/<feature-id>-formulation.md
• docs/numerical-reviews/<feature-id>-review.md
• docs/io-definitions/<feature-id>-io.md

Keep documents in Korean Markdown. Keep FEM symbols, Abaqus keywords, status values, schema keys, and requirement IDs in English.

FORMULATION SPEC Checklist

Include these formulation sections when the feature requires a formulation document:

• Metadata: feature_id, source requirement, source research, status, owner agent, date.
• Scope and Assumptions: analysis type, element type, small/large deformation, linear/nonlinear, material model boundary, coordinate system, units.
• Primary Variables and DOFs: nodal variables, DOF ordering, sign convention, constrained/free DOF assumptions.
• Strong Form and Boundary Conditions: governing equation, Dirichlet boundary, Neumann boundary, natural boundary terms.
• Weak or Variational Form: test functions, integration by parts, internal virtual work, external virtual work.
• Discretization: interpolation, shape functions, nodal layout, partition of unity, Kronecker delta.
• Kinematics: strain-displacement relation, B matrix or kinematic operator, deformation gradient or strain measure when needed.
• Constitutive Contract: elasticity matrix or stress-update assumptions, material state variables, constraints; never C++ APIs.
• Element Equations: internal force or residual, external force, stiffness or tangent matrix, mass/damping only when required, vector/matrix dimensions.
• Mapping and Numerical Integration: reference coordinates, isoparametric mapping, Jacobian, determinant validity, derivative transform, Gauss points, weights, full/reduced/selective/analytical integration policy.
• Output Recovery: displacement, reaction, element force, strain, stress, output location, nodal/element/integration-point/centroidal/nodal extrapolation policy.
• Algorithm Pseudocode: math-level element routine and assembly flow only.
• Numerical Risks: rigid body modes, patch test, symmetry, positive definiteness, hourglass, shear locking, volumetric locking, distortion, singular Jacobian, conditioning, convergence risk.

NUMERICAL REVIEW CHECK Rules

When reviewing a formulation, lead with findings and required revisions:

• Treat confirmed defects, numerical risks, open questions, and downstream test recommendations as separate categories.
• Check dimensions of equations, vectors, matrices, integration terms, residuals, and stiffness/tangent matrices.
• Check signs for loads, reactions, stresses, internal force, residual, and element force output.
• Check coordinate transforms, local/global conventions, output locations, and component naming.
• Check Jacobian rules, determinant validity, derivative transform, distortion policy, integration weights, and Gauss point counts.
• Check whether patch tests, rigid body mode checks, symmetry checks, positive definiteness expectations, locking/hourglass risks, and conditioning risks are documented.
• Use pass-for-implementation-planning only when the specification is complete enough for implementation planning; this is not release approval.

I/O CONTRACT Checklist

Include these I/O sections when the feature requires an Abaqus input or result CSV contract:

• Abaqus Input Scope: input format is Abaqus .inp; define supported documentation source/version and state that FESA supports only this feature's keyword subset.
• Syntax Policy: case-insensitivity, comma-separated keyword/data lines, comments beginning with **, continuation, includes, labels, line-length limits, ASCII assumptions, empty data fields.
• Model Data Mapping: nodes, elements, node sets, element sets, material, section, coordinates, units.
• History Data Mapping: steps, analysis procedure keyword, boundary conditions, loads, output requests.
• Internal Model Contract: semantic fields for node label, element label, element type, connectivity, set membership, material, section, boundary condition, load, step, output request; never C++ classes or function signatures.
• Output and CSV Schemas: column names, ID fields, component naming, coordinate system, units, step/frame identity, and quantity location.
• Validation Rules: required fields, duplicate labels, missing references, unsupported keywords, set expansion, coordinate conventions, output quantity availability.

Default Abaqus keyword checklist:

• *HEADING
• *INCLUDE
• *NODE
• *NSET
• *ELEMENT
• *ELSET
• *MATERIAL
• *ELASTIC
• feature-specific section keyword such as *SOLID SECTION, *BEAM SECTION, or *SHELL SECTION
• *BOUNDARY
• *CLOAD
• *DLOAD
• *STEP
• feature-specific procedure keyword such as *STATIC
• *OUTPUT
• *NODE OUTPUT
• *ELEMENT OUTPUT

Default result CSV checklist:

• displacements.csv: step/frame, node id, displacement components, coordinate system, units.
• reactions.csv: step/frame, constrained node id, reaction force components, sign convention, units.
• element_forces.csv: step/frame, element id, location, component, value, sign convention, units.
• stresses.csv: step/frame, element id, integration point or recovery location, component, value, coordinate system, units.
• Optional strains.csv and energy_or_residual.csv only when upstream documents define schema and acceptance need.

Handoff

Prepare downstream handoff without deciding implementation structure:

• Numerical Review Agent: derivations, assumptions, numerical risks, dimensions, open issues.
• I/O Definition Agent: required inputs, outputs, units, coordinates, output locations, Abaqus keyword needs.
• Reference Model Agent: benchmarkable quantities, patch test needs, expected invariants, singular or invalid-input cases.
• Implementation Planning Agent: math-level pseudocode, parser acceptance cases, CSV writer tests, numerical risk tests, acceptance-relevant quantities.

Boundaries

• Do not implement C++ code.
• Do not design C++ APIs.
• Do not decide C++ file ownership or storage layout.
• Do not implement parsers.
• Do not run Abaqus, Nastran, or any reference solver.
• Do not generate reference CSVs.
• Do not create or modify reference artifacts.
• Do not change tolerance policies.
• Do not perform reference verification or physics validation.
• Do not approve release readiness.

Quality Gate

Before marking a specification ready for implementation planning:

• Requirements and research sources are traceable, or missing source evidence is marked needs-research.
• Strong Form, Weak or Variational Form, Discretization, Kinematics, Element Equations, Mapping and Numerical Integration, Output Recovery, and Numerical Risks are complete enough for the feature scope.
• Shape functions include partition of unity and Kronecker delta expectations when applicable.
• Mapping includes reference coordinates, Jacobian, determinant validity, and derivative transform.
• Numerical review checks cover dimensions, signs, DOF ordering, coordinate transforms, integration weights, output locations, rigid body modes, patch tests, symmetry, positive definiteness, hourglass, locking, singular Jacobian, and conditioning.
• Abaqus Input Scope, Model Data Mapping, History Data Mapping, Internal Model Contract, Output and CSV Schemas, and Validation Rules are documented when I/O is in scope.
• Unsupported Abaqus keyword behavior is classified as unsupported, ignored-with-warning, or requires-user-decision.
• No C++ API, parser implementation, reference value, or tolerance policy is invented.

Common Mistakes

• Advancing a formulation without dimensions, signs, coordinate system, or output location.
• Treating a feature as fully Abaqus-compatible when only a keyword subset is defined.
• Hiding uncertain derivations inside implementation pseudocode instead of recording open issues.
• Defining CSV columns without units, coordinate system, step/frame identity, or quantity location.
• Treating pass-for-implementation-planning as solver verification or release readiness.