FESADev/docs/numerical-reviews/README.md

수치 검토 리포트 작성 가이드

이 디렉터리는 Numerical Review Agent가 작성하거나 제안한 기능별 수치 검토 리포트를 보관하는 위치다.

기본 파일명은 docs/numerical-reviews/<feature-id>-review.md 형식을 사용한다. 각 리포트는 Formulation Agent의 정식화 문서를 독립 검토해, 구현 계획 단계로 넘겨도 되는지 판단한다.

Numerical Review Agent 역할

Numerical Review Agent는 정식화의 수학적 일관성, 수치 안정성 위험, 검증 준비 상태를 검토한다.

수행한다:

• 수식의 차원, 부호, 좌표 변환, 적분 규칙을 검토한다.
• B matrix 또는 kinematic operator, constitutive contract, element equation을 검토한다.
• rigid body modes, patch test, symmetry, positive definiteness를 확인한다.
• hourglass, shear locking, volumetric locking, distortion, singular Jacobian, conditioning 위험을 식별한다.
• 구현 계획 전에 필요한 정식화 수정, 연구 보강, reference model 요구사항을 작성한다.

수행하지 않는다:

• C++ 코드를 구현하지 않는다.
• 정식화 문서를 직접 수정하지 않는다.
• C++ API나 파일 구조를 설계하지 않는다.
• Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
• Abaqus reference CSV 파일을 생성하거나 수정하지 않는다.
• release readiness를 승인하지 않는다.
• 레퍼런스 결과와 구현 솔버 결과의 일치 여부를 판정하지 않는다.

문서 템플릿

# <feature title> Numerical Review

## Metadata
- feature_id: <feature-id>
- source_formulation: docs/formulations/<feature-id>-formulation.md
- status: pass-for-implementation-planning | needs-formulation-revision | needs-research | needs-reference-model | blocked
- owner_agent: numerical-review-agent
- date: <YYYY-MM-DD>

## Review Verdict
- verdict: pass-for-implementation-planning | needs-formulation-revision | needs-research | needs-reference-model | blocked
- reason: <판정 이유>

## Critical Findings
- <구현 전 반드시 수정할 수식 또는 수치 결함>

## Numerical Risk Assessment
- rigid_body_modes: <check/risk>
- patch_test: <check/risk>
- symmetry: <check/risk>
- positive_definiteness: <check/risk>
- hourglass: <check/risk or N/A>
- shear_locking: <check/risk or N/A>
- volumetric_locking: <check/risk or N/A>
- distortion: <check/risk>
- singular_jacobian: <check/risk>
- conditioning: <check/risk>
- convergence: <check/risk or N/A>

## Consistency Checks
- units: <pass/fail/TBD>
- dimensions: <pass/fail/TBD>
- signs: <pass/fail/TBD>
- dof_ordering: <pass/fail/TBD>
- coordinate_transforms: <pass/fail/TBD>
- matrix_vector_dimensions: <pass/fail/TBD>
- integration_weights: <pass/fail/TBD>
- output_locations: <pass/fail/TBD>

## Verification Readiness
- unit_tests: <필요한 단위 테스트>
- patch_tests: <필요한 patch test>
- mms_or_mes: <MMS/MES 후보 또는 N/A>
- benchmark_reference_comparison: <필요한 benchmark/reference 비교>
- missing_evidence: <누락된 검증 근거>

## Required Revisions

### Formulation Agent
- <정식화 수정 지시>

### Research Agent
- <연구 보강 지시>

### Reference Model Agent
- <reference model 또는 artifact 요구사항>

## Downstream Handoff

### Implementation Planning Agent
- <테스트와 acceptance criteria로 변환할 항목>

### Reference Model Agent
- <테스트 모델로 변환할 항목>

품질 기준

• 확인된 결함, 위험, open question을 구분해야 한다.
• pass-for-implementation-planning은 구현 계획으로 넘겨도 된다는 뜻이며 기능 완료나 release 승인이 아니다.
• 정식화 문서를 직접 수정하지 않고 필요한 수정을 명확히 지시해야 한다.
• 모든 검토는 dimension, sign, DOF ordering, coordinate transform, Jacobian, integration weight, element equation, output recovery를 포함해야 한다.
• numerical risk는 rigid body modes, patch test, symmetry, positive definiteness, hourglass, locking, singular Jacobian, conditioning을 포함해야 한다.