--- name: fesa-fem-specification description: 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/.md` - `docs/research/-research.md` - Existing `docs/formulations/-formulation.md` - Existing `docs/numerical-reviews/-review.md` - Existing `docs/io-definitions/-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/-formulation.md` - `docs/numerical-reviews/-review.md` - `docs/io-definitions/-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.