FESADev/docs2/SOLVER_SKILL_DESIGN.md

Structural FEM Solver Skill Design

1. 목적

Project-local skill은 범용 유한요소 구조해석 solver feature를 요구사항부터 release readiness까지 일관되게 처리하는 재사용 절차다. Agent가 stage의 책임과 write boundary를 소유하고, skill은 그 stage에서 필요한 판단 방법, evidence와 output contract를 제공한다.

실행 지침의 source of truth는 각 .codex/skills/<skill-name>/SKILL.md다. 공통 workflow와 상태 전이는 docs/SOLVER_AGENT_DESIGN.md, 수치 비교 정책은 docs/TOLERANCE.md가 소유한다. Skill entrypoint는 이 공통 규칙을 반복하지 않고 역할에 필요한 차이만 제공한다.

2. 설계 원칙

• 이름과 description은 실제 activation boundary를 구분할 수 있어야 한다.
• SKILL.md에는 목적, 필요한 입력, 핵심 workflow, output/evidence와 hard boundary만 둔다.
• 해석 유형별 상세 checklist, toolchain 절차처럼 조건부 정보는 references/에서 필요한 경우에만 읽는다.
• Skill은 승인된 user/project scope를 확장하거나 외부 실행 권한을 암시하지 않는다.
• 산출물은 docs/features/<feature-id>/의 공통 feature bundle에 둔다.
• 모든 stage는 공통 handoff envelope와 다섯 outcome을 사용한다.
• Input, result container, tabular comparison format, compiler와 build adapter는 project/feature contract가 선택한다. 특정 형식을 solver identity로 고정하지 않는다.
• Read-only 조사와 reversible in-repository 판단은 자율 수행한다. Critical decision만 needs-user-decision으로 반환한다.

3. Workflow skill inventory

Stage	Skill	대표 산출물
Requirements	fem-requirements-baseline	requirements.md
Research	fem-research-evidence	research.md
Formulation	fem-formulation-spec	formulation.md
Numerical review	fem-numerical-review	numerical-review.md, reference-model.md
I/O definition	fem-io-contract	io.md
Planning/implementation/correction	fem-implementation-tdd	implementation-plan.md, implementation-report.md, build-test.md, reference-comparison.md, 필요 시 corrections.md
Physics evaluation	fem-physics-review	physics-evaluation.md
Release readiness	fem-release-readiness	release.md

위 8개가 lifecycle workflow skill이다. 폴더명, frontmatter name, agent prompt와 agents/openai.yaml invocation name은 항상 동일해야 한다.

4. Stage별 책임 분리

Requirements

fem-requirements-baseline은 scope, observable requirement, acceptance intent와 requirement-verification matrix를 정의한다. Formulation, tolerance 값, API와 storage schema를 선결정하지 않는다.

Research

fem-research-evidence는 governing theory, primary source, benchmark와 reference convention의 신뢰성·적용 한계를 정리한다. 사실, 계산, 추론과 evidence gap을 구분하며 formulation 결론을 대신 만들지 않는다.

Formulation

fem-formulation-spec은 strong/weak form, variables/DOF, kinematics, constitutive update, residual/tangent, integration, state와 recovery를 implementation-neutral 수학 계약으로 만든다. 선택된 linear/nonlinear/dynamic/eigen/contact/material family의 reference만 읽는다.

Numerical review

fem-numerical-review는 formulation을 독립 검토하고 requirement를 falsify할 verification coverage를 정의한다. Logical quantity, identity, location, units와 tolerance 근거까지 소유하지만 physical dataset/file layout은 I/O stage에 남긴다.

I/O definition

fem-io-contract은 선택된 external syntax와 semantic model, versioned result schema 및 comparison identity 사이를 mapping한다. 미지원 semantic construct, validation과 diagnostic을 명시한다. Subset 지원을 full compatibility로 표현하지 않는다.

Planning, implementation와 correction

fem-implementation-tdd는 approved upstream bundle을 작은 RED/GREEN step으로 계획하고 C++ 변경, configured build/test와 필요한 reference comparison evidence를 만든다. Implementation은 upstream contract, tolerance 또는 reference artifact를 결과에 맞춰 고치지 않는다.

Executor의 process/session 재시도는 transport attempt이며 Coordinator의 normalized failure/correction budget과 별개다. 동일 retry_key의 correction은 한 번만 허용한다.

Physics evaluation

fem-physics-review는 numerically passing result가 문서화된 equilibrium, sign, symmetry, energy, mode와 model coverage 기대를 만족하는지 독립 검토한다. 새 acceptance를 즉석에서 만들지 않는다.

Release readiness

fem-release-readiness는 동일 feature/contract revision의 traceability, gate evidence, limitations와 release-note draft를 감사한다. Readiness verdict는 publish, tag, deploy 또는 external release 권한이 아니다.

5. Supporting skill

Skill	적용 조건
fem-theory-query	사용자가 configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때
harness	implementation phase를 만들거나 bounded Executor 작업을 수행할 때
review	repository diff를 architecture, numerical, test와 evidence 기준으로 읽기 전용 검토할 때

fem-theory-query는 일반 FEM 질문 전체를 가로채지 않는다. Vault path는 environment, project instruction 또는 untracked local override에서 해석하며 workstation 절대 경로를 commit하지 않는다. External research나 vault write는 해당 요청과 권한이 있을 때만 수행한다.

Harness skill은 build/test command authority와 Executor/runtime ownership을 정의한다. Hook은 guardrail이며 RED observation이나 complete sandbox를 대신하지 않는다.

6. 공통 evidence

Skill output은 해당 stage에 필요한 부분만 작성하되 handoff에는 다음을 포함한다.

• feature_id, stage, outcome, next_owner
• evidence_paths, current contract revision과 artifact identity/hash
• decisive finding, command, exit code, duration과 test count
• comparison quantity, identity, units, metric와 tolerance source
• failure_classification, retry_key, attempt
• escalation_class, actionable blocker와 residual risk

필요한 명령이 실패했거나 실행되지 않았고 blocking evidence가 stale/missing이면 pass를 반환하지 않는다. Raw log 전체를 모든 skill 문서에 복사하지 않고 재현 가능한 digest와 원본 artifact path를 남긴다.

7. Abaqus reference policy

Abaqus는 project가 선택한 경우 다음 공개 observable convention의 기준으로 사용한다.

• input keyword와 option의 문서화된 syntax/semantics
• model data와 history/step data의 구분
• element formulation, integration과 output location 정의
• analysis procedure와 convergence 개념
• verification guide의 benchmark 구성과 expected physical behavior

Skill은 비공개 내부 구현을 추정하지 않고 full compatibility나 solver equivalence를 주장하지 않는다. External Abaqus execution은 저장된 artifact를 읽는 것과 다른 권한이며 라이선스, 자격증명, 비용과 명시된 command scope가 확보된 경우에만 수행한다.

8. Autonomous decision boundary

Skill은 approved contract 안의 내부 naming/layout, test 분해, diagnostic, 문서 형식, 기술 근거가 유일한 convention과 명백한 결함 수정을 자율적으로 처리한다. Numerical Review는 docs/TOLERANCE.md와 evidence로 feature-specific metric/tolerance를 결정할 수 있다.

지원 physics/범위, 공개 compatibility, authoritative schema, product acceptance를 바꾸는 tolerance, 상충하는 필수 reference evidence, 외부 권한 또는 destructive/release 작업만 사용자 결정이 필요하다. “계속할까요?” 같은 routine approval을 stage 사이에 추가하지 않는다.

9. Validation

Skill 변경 후 다음을 검증한다.

• lifecycle skill 8개와 supporting skill의 frontmatter parse
• 폴더명, name, openai.yaml invocation과 agent 참조 일치
• relative reference link의 존재와 repository containment
• canonical output path와 common outcome vocabulary
• product-specific legacy name과 machine-specific absolute path 부재
• realistic requests를 이용한 최소 forward-test

Project에 validator가 제공되면 해당 validator와 repository pytest suite를 모두 실행한다. Validator 부재 또는 미실행을 성공으로 간주하지 않는다.