FESADev/.codex/skills/fesa-feature-definition/SKILL.md

name, description

name	description
fesa-feature-definition	Use when defining or reviewing FESA solver feature requests, requirements, research questions, acceptance criteria, verification matrices, tolerance needs, or downstream handoffs before FEM formulation, I/O definition, reference modeling, implementation, or release.

FESA Feature Definition

Overview

Use this skill to turn a FESA solver feature request into a verifiable Feature Definition Packet. Define what the solver feature must do, how it will be verified, what research is needed, and what downstream agents need as input.

This skill is shared by Requirement Agent, Research Agent, Coordinator Agent, and Release Agent. It is not a formulation, implementation, reference generation, or release approval workflow.

Inputs

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

• docs/SOLVER_SKILL_DESIGN.md
• docs/SOLVER_AGENT_DESIGN.md
• AGENTS.md
• User feature request or Coordinator handoff
• Existing docs/requirements/<feature-id>.md
• Existing docs/research/<feature-id>-research.md
• Relevant coordination or release reports when reviewing traceability

Workflow

1. Feature Intake: assign a stable feature_id, summarize the requested capability, and separate user-visible behavior from implementation detail.
2. Solver Context: classify analysis type, element family, DOFs, material model boundary, loads, boundary conditions, units, coordinates, and required result quantities.
3. Requirement Drafting: write singular shall requirements. Keep each requirement measurable, necessary, unambiguous, feasible, and traceable.
4. Verification Planning: create a Requirement Verification Matrix that maps each must requirement to a verification method, acceptance criterion, compared quantity, artifact need, and tolerance decision.
5. Research Framing: list Research Questions for missing theory, benchmark values, official solver manual details, source quality, or applicability limits.
6. Quality Check: mark unverifiable, ambiguous, or missing decisions as needs-user-decision; do not invent values.
7. Downstream Handoff: package only the facts needed by Research, Formulation, I/O Definition, Reference Model, Implementation Planning, Release, or Coordinator agents.

Output Contract

The primary output is a Feature Definition Packet. The default save candidate is docs/requirements/<feature-id>.md; Research Agent may later create docs/research/<feature-id>-research.md.

Include these sections:

• Metadata: feature_id, title, status, owner_agent, date, source request
• Feature Summary: purpose and expected solver behavior
• Included Scope: analysis, element, material, load, boundary, I/O, and result scope
• Excluded Scope: explicitly deferred capabilities
• Solver Context: units, coordinate system, DOFs, sign conventions, output quantities
• Requirement Records: one record per shall requirement
• Requirement Verification Matrix: requirement id, method, acceptance criterion, artifact, tolerance
• Research Questions: source gaps and benchmark questions for Research Agent
• Reference Artifact Needs: expected model.inp, metadata.json, and required CSVs
• Tolerance Decisions: known tolerance policies and unresolved tolerance decisions
• Open Issues: needs-user-decision, needs-research, or needs-reference-artifacts
• Downstream Handoff: target agent, required inputs, expected output, stop condition

Requirement record format:

id: FESA-REQ-<FEATURE>-###
statement: "The FESA solver shall ..."
category: functional | physics | numerical | input | output | verification | constraint
rationale: "<why this is needed>"
source: user | docs | standard | benchmark | derived
priority: must | should | could
verification_method: test | analysis | inspection | demonstration | reference-comparison
acceptance_criteria: "<measurable pass/fail rule>"
tolerance: "<absolute/relative/norm tolerance or N/A with reason>"
trace_to:
  parent_need: "<need id or statement>"
  downstream_agents: ["Research Agent", "Formulation Agent"]
status: draft | needs-user-decision | approved

Verification Matrix Rules

• Use test for deterministic unit, parser, or integration behavior.
• Use analysis for checks proven by calculation, dimensional reasoning, or theoretical derivation.
• Use inspection for static documents, schemas, files, and artifact presence.
• Use demonstration only when pass/fail can be observed without reference comparison.
• Use reference-comparison for stored reference artifact comparisons against displacements, reactions, element internal forces, stresses, and optional strain, energy, or residual quantities.
• If a tolerance is missing, write the tolerance need as an open issue instead of choosing one.
• If a required CSV or metadata.json is missing, do not mark the feature definition ready for downstream implementation.

Boundaries

• Do not finalize FEM formulations.
• Do not write weak forms, shape functions, element matrices, or C++ API decisions as approved requirements.
• Do not implement C++ code.
• Do not create implementation plans beyond downstream handoff notes.
• Do not run Abaqus, Nastran, or any reference solver.
• Do not generate reference CSVs.
• Do not change stored reference artifacts or tolerance policies.
• Do not approve release readiness.

Quality Gate

Before marking the packet approved or ready for a downstream agent, verify:

• Included and excluded scope are explicit.
• Every must requirement has a verification method and measurable acceptance criteria.
• Numerical requirements include units, coordinate system, quantity, and tolerance status.
• Reference-comparison requirements name the physical quantities and required artifacts.
• Phrases such as "same as Abaqus", "accurate", or "fast" are converted into measurable criteria or open issues.
• Implementation details are separated from requirements and moved to downstream handoff.
• Open decisions are marked needs-user-decision or assigned to a downstream agent.

Common Mistakes

• Treating "Abaqus-compatible" as a requirement without a supported keyword subset and verification evidence.
• Turning preferred implementation details into shall requirements.
• Advancing to formulation when tolerance, unit, coordinate, or output-location decisions are absent.
• Treating a reference artifact request as permission to run Abaqus or create CSVs.
• Declaring release readiness from requirement quality alone.