FESADev/docs/SOLVER_SKILL_DESIGN.md

FESA Solver Skill Design

목적

이 문서는 FESA의 8단계 feature workflow에서 사용하는 project-local skill 구성을 정의한다. Agent는 역할과 책임 단위이고 skill은 여러 agent가 재사용하는 절차, 품질 gate와 handoff 단위다. 모든 feature별 skill output은 docs/<feature-id>/에 기록한다.

실제 실행 지침의 source of truth는 각 .codex/skills/<skill-name>/SKILL.md다. 이 문서는 skill inventory와 책임 분리를 사람이 읽을 수 있게 설명한다.

설계 원칙

• 각 skill은 SKILL.md의 name, description frontmatter와 agents/openai.yaml UI metadata를 가진다.
• Skill은 입력, workflow, output contract, boundaries, quality gate와 handoff를 정의한다.
• 공통 상위 계약은 AGENTS.md와 docs/SOLVER_AGENT_DESIGN.md다.
• Abaqus, Nastran 또는 다른 reference solver 실행과 reference CSV 생성/수정은 skill 범위가 아니다.
• C++ 절차는 C++17 이상, MSVC x64 Debug, CMake/CTest와 TDD를 따른다.
• 검증 명령은 .harness/config.json을 우선하고 없으면 docs/HARNESS.md의 자동 감지 기본값을 따른다.
• Skill output path에는 agent별 폴더를 만들지 않고 docs/<feature-id>/만 사용한다.

8개 workflow skill

Skill	8단계 적용 과정	주요 사용자 sub-agent	docs/<feature-id>/ 대표 산출물
fesa-requirements-baseline	1. 요구조건	Requirement Agent	requirements.md
fesa-research-evidence	2. 연구	Research Agent	research.md
fesa-formulation-spec	3. 정식화	Formulation Agent	formulation.md
fesa-numerical-review	4. 수치 검토 + reference readiness	Numerical Review Agent	numerical-review.md, reference-model.md
fesa-io-contract	5. I/O 정의	I/O Definition Agent	io.md
fesa-cpp-msvc-tdd	6. 구현 계획 + C++ 구현 + build/test + reference comparison	Implementation Planning Agent, Implementation Agent, Correction Agent	implementation-plan.md, implementation-report.md, build-test.md, reference-comparison.md, 필요 시 corrections.md
fesa-physics-sanity	7. 물리 검토	Physics Evaluation Agent	physics-evaluation.md
fesa-release-readiness	8. 배포 준비	Release Agent	release.md

통합 후 FESA workflow skill은 위 8개가 전부다.

Skill별 핵심 계약

fesa-requirements-baseline

• 기능 요청을 검증 가능한 baseline으로 만든다.
• shall 문장과 FESA-REQ-<FEATURE>-### id를 사용한다.
• 모든 must 요구조건에 verification method와 acceptance criteria를 연결한다.
• FEM 정식화, C++ 구현, reference value 생성 또는 release 판정은 하지 않는다.

fesa-research-evidence

• Research question, source inventory, reliability tier, benchmark 후보와 applicability limit를 정리한다.
• 검증된 사실과 추론을 분리하고 source gap은 open issue로 남긴다.
• FEM 정식화나 reference value를 확정하지 않는다.

fesa-formulation-spec

• Strong form, weak form, discretization, kinematics, constitutive contract와 element equation을 구분한다.
• Jacobian, derivative transform, numerical integration, output recovery와 numerical risk를 명시한다.
• C++ API, parser ownership 또는 file layout을 설계하지 않는다.
• Numerical Review 전에는 최종 구현 승인 상태로 두지 않는다.

fesa-numerical-review

이 skill은 numerical correctness와 reference readiness 절차를 함께 소유한다.

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

• Dimensions, signs, DOF order, coordinate transform, Jacobian, integration, stiffness symmetry, rigid-body mode, patch test, hourglass와 locking을 독립 검토한다.
• 기존 exact input/required CSV를 inventory하고 blocking/warning quantity, source identity와 component matching, missing/extra/duplicate/nonfinite row precheck와 승인 tolerance를 정한다.
• numerical-review.md와 reference-model.md를 함께 산출한다.
• Logical quantity와 source identity까지만 정의한다. 최종 HDF5 dataset projection은 I/O Definition Agent에 handoff한다.
• 두 문서가 준비된 pass-for-io-definition만 다음 단계 진행을 허용한다.

fesa-io-contract

• 지원할 Abaqus .inp keyword subset, semantic model mapping과 validation rule을 정의한다.
• Authoritative results.h5 schema, units, coordinates, step/frame, row identity와 component를 정의한다.
• Reference readiness의 logical quantity/source identity를 최종 HDF5 dataset projection과 CSV column mapping으로 연결한다.
• Parser 구현이나 full Abaqus compatibility를 주장하지 않는다.

fesa-cpp-msvc-tdd

이 skill은 implementation planning, TDD implementation, MSVC validation, failure correction과 reference comparison 절차를 함께 소유한다.

RED -> OBSERVED FAILURE -> MINIMAL GREEN -> FOCUSED VERIFY
    -> FULL MSVC BUILD/CTEST -> ARTIFACT CHECK
    -> COMPARE -> CLASSIFY -> REPORT

• Planning 시 project-local harness로 user-approved multi-Step plan을 만들고 implementation-plan.md를 산출한다.
• C++ production 변경에는 관련 C++ test가 있어야 하며 targeted RED와 후속 GREEN evidence를 기록한다.
• .harness/config.json이 선택한 MSVC x64 Debug build/CTest를 실행하고 명령, exit code, duration, output tail과 failure classification을 build-test.md에 기록한다.
• Reference artifact check 뒤 HDF5/CSV row를 source identity와 component로 대응시킨다. Missing, extra, duplicate와 nonfinite required row는 tolerance 전에 실패하며 warning-only quantity는 blocking result를 바꾸지 않는다.
• Implementation-owned 실패를 먼저 수정한다. 반복되거나 불명확한 실패는 Coordinator를 통해 Correction Agent로 보내고 corrections.md에 재작업 evidence를 남긴다.
• 성공 시 implementation-report.md, build-test.md, reference-comparison.md와 pass-for-physics-evaluation handoff를 반환한다.
• Requirements, formulation, numerical/reference 계약, I/O 계약, reference artifact 또는 tolerance policy를 변경해 결과를 맞추지 않는다.

기본 validation sequence는 다음과 같다.

cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug -R <feature-or-label> --output-on-failure
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure

fesa-physics-sanity

• Implementation gate 통과 후 equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid-body mode와 model coverage를 검토한다.
• 문서화된 물리 기대값이 없으면 pass를 선언하지 않는다.
• pass-for-release-agent는 Release Agent 검토 가능 상태만 의미한다.

fesa-release-readiness

• GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT 순서를 따른다.
• Requirements부터 physics까지 동일 feature evidence와 필수 pass status를 확인한다.
• Known limitations, Release Notes Draft와 ready-for-release 여부를 기록한다.
• 사용자 요청 없이 publish, deploy, package, tag, commit 또는 external release를 수행하지 않는다.

Supporting skills

다음은 8개 workflow skill 수에 포함하지 않는 supporting skill이다.

• fem-theory-query: FEM wiki의 이론, benchmark, solver manual과 verification evidence 조회.
• project-local harness: Implementation Planning의 Step 초안, 사용자 승인 후 phase materialization과 별도 요청에 의한 executor 실행.
• review: AGENTS, architecture, tests와 build requirement에 대한 repository change review.

Implementation Planning Agent는 project-local harness를 반드시 사용한다. 사용자에게 자기완결적 Step 초안을 먼저 제시하고 승인 후에만 phases/index.json, phases/<task-name>/index.json, phases/<task-name>/stepN.md를 생성한다. scripts/execute.py는 별도 사용자 요청 없이 실행하지 않는다.

Agent와 skill 관계

Agent	주로 사용하는 skill
Coordinator Agent	단계 owner가 반환한 skill evidence를 audit하고 dispatch/closure 관리
Requirement Agent	fesa-requirements-baseline
Research Agent	fesa-research-evidence, 필요 시 fem-theory-query
Formulation Agent	fesa-formulation-spec
Numerical Review Agent	fesa-numerical-review, 필요 시 fem-theory-query
I/O Definition Agent	fesa-io-contract
Implementation Planning Agent	project-local harness, fesa-cpp-msvc-tdd
Implementation Agent	fesa-cpp-msvc-tdd
Correction Agent	fesa-cpp-msvc-tdd
Physics Evaluation Agent	fesa-physics-sanity
Release Agent	fesa-release-readiness

검증 기준

Skill 구성은 실제 .codex/skills/ 파일과 repository pytest suite를 기준으로 검증한다.

• 8개 FESA workflow skill의 SKILL.md 존재 여부
• YAML frontmatter의 name, description
• 공통 section: Inputs, Workflow, Output Contract, Boundaries, Quality Gate, Handoff
• AGENTS.md와 docs/SOLVER_AGENT_DESIGN.md 참조
• Skill-specific procedure와 docs/<feature-id>/ output contract
• agents/openai.yaml UI metadata와 skill name reference
• TOML 및 YAML metadata parseability

Repository validation은 다음 명령을 사용한다.

uv run --with pytest python -m pytest -v -rs

개별 skill schema는 현재 Codex 설치의 skill-creator validator로 점검하되 사용자 홈의 절대 경로를 프로젝트 계약으로 두지 않는다.