FESADev/docs/SOLVER_SKILL_DESIGN.md

# Structural FEM Solver Skill Design

## 목적과 적용 원칙

Project-local skill은 필요한 FEM 판단과 검증 방법을 제공한다. 고정 lifecycle의 모든
skill을 순회하지 않는다. 메인 assistant 또는 할당된 specialist는 현재 작업에 필요한
skill과 직접 영향받는 계약만 읽는다.

실행 지침의 원본은 각 `SKILL.md`다. 역할·인계는
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), 공통 운영 결정은
[ADR-028](ADR.md#adr-028), 수치 비교 정책은 [TOLERANCE](TOLERANCE.md)를 따른다.

- 이름과 description은 실제 사용할 조건을 구분한다.
- `SKILL.md`에는 목적·필요 입력·판단 규칙·결과·수정 경계를 둔다.
- 긴 유도나 toolchain·해석 계열별 절차는 `references/`에서 필요할 때만 읽는다.
- 같은 문맥에서 읽은 변경 없는 자료를 재독하거나 모든 Feature 문서를 인계에 넣지 않는다.
- Skill은 승인된 작업 범위나 외부 실행 권한을 넓히지 않는다.
- FESA가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 수치 계약은 유지한다.
- 필요한 산출물만 [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 작성한다.
  빈 보고서, 고정 envelope·outcome, 자동 commit이나 workflow 상태 파일을 요구하지 않는다.

## FEM skill inventory

다음 8개 skill은 [`.codex/skills`](../.codex/skills)에 있다. 대표 산출물은 필요한
경우의 예시이며 모든 작업에 별도 파일을 생성하라는 요구가 아니다.

| Skill | 사용할 때와 필요한 입력 | 결과와 경계 |
| --- | --- | --- |
| `fem-requirements-baseline` | 지속할 scope·acceptance 계약이 필요할 때 사용자 요구와 관련 기존 계약 확인 | 검증 가능한 요구·acceptance; 복잡하면 `requirements.md`와 matrix로 분리. 수식·schema·수치 기준을 선결정하지 않음 |
| `fem-research-evidence` | 이론·benchmark 근거가 부족할 때 구체적인 solver 질문과 관련 원문 확인 | 출처 있는 연구 근거·적용 한계·gap. 사실과 추론을 구분하고 정식화 결론을 대신하지 않음 |
| `fem-formulation-spec` | 새 수학 모델이나 변경된 정식화가 필요할 때 관련 요구·근거 확인 | DOF/kinematics, residual/tangent, integration, state update와 recovery 계약. 구현이나 자기 승인을 하지 않음 |
| `fem-numerical-review` | 정식화·안정성·검증 범위의 독립 검토가 필요할 때 수식과 evidence 확인 | 수치 위험·analytical/invariant 검증·reference-model 준비 판단. 비교량·identity·location·units를 정의하고 저장 layout은 I/O에 남김 |
| `fem-io-contract` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경될 때 관련 계약 확인 | 지원 subset, fail-closed 진단, 결과 의미와 저장·비교 mapping. 공개 compatibility를 임의 확대하지 않음 |
| `fem-implementation-tdd` | 솔버 계획·구현·수정 시 할당 작업, 영향받는 계약과 build 설정 확인 | 최소 코드·의미 있는 테스트·필요한 계획과 검증 evidence. 상위 계약·reference·tolerance를 결과에 맞추어 수정하지 않음 |
| `fem-physics-review` | 결과의 평형·부호·대칭·energy·mode·coverage 평가가 필요할 때 결과와 승인 기준 확인 | 물리적 타당성과 적용 한계. 새 acceptance를 즉석에서 만들거나 코드·계약을 수정하지 않음 |
| `fem-release-readiness` | 사용자가 release-readiness 감사를 명시 요청할 때 해당 Feature 계약·결과·제한 확인 | 필수 evidence와 잔여 위험에 대한 내부 권고. 필수 lifecycle stage나 외부 release 권한이 아님 |

수식·요소·재료·적분·상태 갱신 변경의 독립 numerical review와 해당 analytical/invariant
검증은 유지한다. 메인은 `fem-implementation-tdd`를 직접 사용하여 계획·구현·일반 실패
수정을 수행할 수 있다. 별도 planning/correction profile이나 Harness phase 파일이 필요하지 않다.

## Supporting skill

| Skill | 적용 조건과 경계 |
| --- | --- |
| `fem-theory-query` | configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때. 일반 FEM 질문 전체에 적용하지 않음 |
| `harness` | 구성된 build/test를 명시적으로 실행할 때. `python scripts/execute.py` 사용; phase 계획·agent 호출·Git 관리 기능 없음 |
| `review` | 요청된 diff와 영향받는 계약·correctness·검증·범위를 읽기 전용 검토할 때. 수정 요청 없이 finding을 고치지 않음 |

`fem-theory-query`의 vault resolution과 citation 규칙을 유지한다. Workstation 절대 경로는
untracked local override 등에 두고 commit하지 않는다. 외부 조사나 vault 수정에는 해당
요청과 권한이 필요하다. Harness는 수치·물리·reference 검증이나 외부 solver 권한을 대신하지
않으며 명령과 설정은 [HARNESS](HARNESS.md)를 따른다.

## 결과와 evidence

결과에는 작업을 지지하는 판단·가정, 변경 파일, 실제 명령·exit code·결정적 판정값,
evidence 경로와 미해결 항목·제한만 필요한 만큼 기록한다. 수치 비교는 quantity,
identity/component, units, metric과 승인된 tolerance source를 확인한다.

실행하지 않았거나 실패한 검사, missing/stale blocking evidence를 통과로 표시하지 않는다.
긴 로그와 이미 정의된 수식을 여러 보고서에 복사하거나 의미 변화 없는 문서 편집마다
revision/hash·gate 기록을 새로 만들지 않는다. 실제 계약이 변경되면 영향받은 evidence의
유효성을 다시 확인한다.

동작 변경은 해당 테스트로 검증하고 버그는 가능한 경우 실패를 재현한다. 변경 중에는 관련
검사를 실행하며 솔버 기능 완료 시 구성된 전체 build/test와 필수 reference 비교를 한 번
수행한다. 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되 이후 변경·
실패가 없으면 반복하지 않는다. 충분한 기존 coverage가 있는 refactor에는 형식적인 새
테스트를 요구하지 않는다.

## Reference와 사용자 결정 경계

Abaqus의 공개 입력 의미·출력 정의·검증 사례는 승인된 범위의 reference로 사용한다.
비공개 내부 알고리즘·상태·결과 생성 절차의 동등성이나 full compatibility를 주장하지
않는다. 수치적 exact equality는 내부 동등성의 evidence가 아니다.

저장된 artifact의 읽기와 외부 Abaqus 실행은 다른 권한이다. Reference 생성·수정·복원은
명시적으로 승인된 범위에서만 다루며 구현 통과를 위해 값을 보정하지 않는다. Numerical
Review는 공통 TOLERANCE 안에서 기능별 비교량·identity·판정 구분을 정의하며 임의로
수치 기준을 완화하지 않는다.

지원 physics·공개 호환성·authoritative schema·acceptance 변경, 해결되지 않은 필수
계약/reference 충돌, 외부 권한이나 파괴적·원격·release 작업은 사용자 결정 경계를 따른다.
이미 승인된 범위의 일반 작업과 skill 인계에 반복 승인을 추가하지 않는다.

## Skill 변경의 확인

Skill 자체를 변경할 때 영향받는 frontmatter, 폴더명·invocation·agent 참조, 상대 링크와
조건부 reference를 확인한다. 변경된 동작에 필요한 최소 검사를 선택하며 제공되는
validator나 관련 repository 검사가 필요하면 실행한다. 문서 설명만 수정하는 작업에
전체 pytest나 solver build를 강제하지 않는다. 정적 검토와 실제 실행 여부를 구분해 기록한다.