FESADev/docs/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를 확장하거나 외부 실행 권한을 암시하지 않는다.
- 산출물은 Coordinator가 생성·관리하는 `docs/<feature-id>/`의 공통 feature bundle에 둔다.
- [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 핵심 결과만 본문에 두고 필요한
  상세 내용은 같은 폴더의 별도 문서로 분리해 참조한다. Feature 관리 문서에서 공통 기준과
  현재 작업을 연결하며 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 보존한다.
- 모든 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 부재 또는 미실행을 성공으로 간주하지 않는다.