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

이 디렉터리는 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 또는 레퍼런스 솔버를 직접 실행하지 않는다.
- reference CSV 결과를 생성하지 않는다.
- release readiness를 승인하지 않는다.
- 레퍼런스 결과와 구현 솔버 결과의 일치 여부를 판정하지 않는다.

## 문서 템플릿

```markdown
# <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을 포함해야 한다.