llm-wiki/.agents/plugins/wiki-superpowers/rules/reporting-standards/findings-template.md

# Per-File Findings + Adversarial Review Template

Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) §"4. 파일별 발견 사항" + §"4-1. 적대 리뷰 결과"
parent: [`README.md`](README.md)

§0~§3, §3-1 Verdict, §5~§8 → [`report-template.md`](report-template.md)
§7.1 self-grep 카운트 규칙 → [`verification-rules.md`](verification-rules.md)

## §4. 파일별 발견 사항 / Per-File Findings

> **분할 시:** §4 상세는 `<topic>-per-file-findings.md` 파일에 들어간다. master report 의 §4 는 한 줄 요약 + 링크만.

각 파일은 자기 하위섹션을 갖는다. "Pillar", "Group", "Theme" 등으로 묶지 않는다. 묶으면 누락 숨겨짐.

각 발견 사항은 **Goal → Problem → Action 인과 사슬** 형식. 단순 의견("성능이 떨어질 수 있다", "고려가 필요하다") 금지. 자세한 컨트랙트는 [`../advisory-depth/contracts-1-causal-chain.md`](../advisory-depth/contracts-1-causal-chain.md) Contract 1 참조.

### 한 파일에서의 finding 개수

각 파일에 대해 분석이 surfacing 한 **모든 gap 을 finding 으로 등재**. 1 파일 = 1 finding 이 아니라 발견된 모든 결함·누락·모호점 빠짐없이 풀어쓴다. 보통 명세 1개 = 2~5 findings.

### Single-finding Justification Gate

파일당 finding 이 정확히 1개라면 §4 하위섹션 끝에 **반드시** 정당화 블록 첨부. 정당화 없이 1개로 끝낸 파일은 자동 `BLOCKED`.

```markdown
#### Single-finding justification (필수, finding이 1개일 때)

다음 4개 중 1개 이상 해당:

- [ ] **단순 명세:** 파일 총 라인 수 < 80, 또는 단일 정책 명세.
       증거: `<file>` 총 <N>줄, 결정 사항 1건.
- [ ] **전수 통과 + 1개 결함:** 검토 <K>개 항목 중 (K−1)개 PASS, 1개 FAIL.
       검토 항목 리스트:
       1. <item 1> — PASS
       2. <item 2> — PASS
       3. <item 3> — FAIL (위 finding)
- [ ] **부분 분석 (PARTIAL):** 시간·범위 제약. §6 Follow-Up 에 추가 분석 대상 명시.
       남은 대상: <list>
- [ ] **단일 critical 차단:** finding 이 너무 critical 하여 다른 항목 분석에 앞서 처리되어야 함.
       이유: <근거>
```

블록 없거나, 4개 중 어느 것도 체크 안 됐거나, "검토 항목" 비어 있으면 → 자동 `BLOCKED`. 정당화는 fluff 아닌 **사실 진술**.

### Zero-finding 파일 처리

진정 0-finding 인 `READ_FULL` 파일은 하위섹션을 생략하지 **않는다**. 명시:

```markdown
**0-finding 정당화 (필수):**
이 파일은 명세 의도와 현재 상태가 일치하며, 검토 <N>개 항목 모두 통과.

검토 항목:
1. <item 1> — PASS — 근거: `<file:line>`
2. <item 2> — PASS — 근거: `<file:line>`
```

`<N>개 항목`은 추상적 아닌 실제 목록. "검토 모두 통과" 한 줄만 → 자동 `BLOCKED`.

### 4.1 `<filename>` (Status: READ_FULL | READ_PARTIAL)

- **요지 / Gist:** <한 문장으로 이 파일이 무엇을 정의하는가>
- **문서 원래 목표:** <이 파일이 정의하려 한 핵심 의도>. 근거: `<file:line>`
- **검토 항목:** <N개 항목 리스트>
- **Findings 요약:** N개 (Critical X · High Y · Medium Z · 통과 W)

#### Finding 4.1.1: <짧은 라벨 — 이 finding 의 한 문장 정체성>

- **심각도:** Critical | High | Medium | Low
- **원래 목표 / Original goal:**
  - **인용:** "<exact text from source, byte-for-byte>"
  - **위치:** `<path>:<line>` (워크스페이스 상대 경로만)
  - **해석:** <한 문장>
- **현재 상태 / Current state:**
  - **인용:** "<exact text>" (또는 "해당 라인 없음 — 명세 자체에 누락")
  - **위치:** `<path>:<line>`
- **실무 가정 / Real-world assumptions (REQUIRED — min 1, typical 2~3):**
  비판이 성립하려면 어떤 실무 가정이 참이어야 하는가? 명시하지 않으면 비판은 "에이전트가 상상한 구현" 표적.
  1. **가정 A:** <e.g., "구현이 동기식", "프로덕션 트래픽 > 1000 RPS", "K8s 환경">
     - **무효 조건:** <이 가정이 거짓일 시나리오>
     - **사용자 검증 방법:** <한 줄 체크>
  2. **가정 B:** ...
- **간극 / Gap (위 가정들이 모두 참일 때):**
  - **구체적 실패 모드:** <X 상황에서 Y 발생 → Z 깨짐 — 1~3개>
  - **재현 조건:** <실패가 일어나는 트리거>
  - **이 finding 이 무효해지는 경우:** <어떤 가정이 거짓이면 비판 자체 사라지는가>
- **필요 조치:** <구체 액션 — 추상 아닌 실행 가능 형태>
- **조치 근거:** <왜 이 액션이 일반 대안보다 이 상황에 맞는가>
- **대안 / Alternatives considered:** [`../advisory-depth/contracts-2-3-4-structure.md`](../advisory-depth/contracts-2-3-4-structure.md) Contract 2 — 가능한 모든 대안 열거 (3~5개)
  - **대안 A:** <라벨> — 적용 상황 / 부적합 이유
  - **대안 B:** ...
  - **대안 C (채택):** <라벨> — 왜 이 상황에 가장 맞는가
- **반대 논거 / Counterarguments (REQUIRED — min 1, typical 2~3):**
  Contract 1 — 권고가 틀릴 수 있는 시나리오.
  1. **반대 A:** <권고가 부적절·과잉인 시나리오>
     - **반대 근거:** <왜 그 시나리오에서 부적절한가>
     - **검증 방법:** <한 줄 체크>
- **구현 단계:** <순서 있는 단계>
  1. <단계 1 — 수정할 파일, 어디에 어떤 내용 들어가는지>
  2. <단계 2>
- **검증 방법:**
  - **자동:** <self-grep / `wiki-link-verifier` / `/lint` / frontmatter grep / wikilink ls 등>
  - **수동:** <Obsidian 그래프뷰 / 리뷰 시 확인 포인트 — 자동 부족 시에만>
- **관련:**
  - 다른 finding 과 결합: <같은 / 다른 파일 finding 과 함께 처리해야 효과>
  - 상호 의존 파일: <영향 주고받는 명세/모듈>

#### Finding 4.1.2: ...

### 4.2 `<next filename>` ...

`NOT_READ` 및 `BLOCKED` 파일은 본 섹션에 자기 하위섹션 X. 매트릭스와 §3 에만 등장.

### Master report 에서의 §4 (분할 시)

분할 시 master report 의 §4 는 한 줄 요약 표만:

```markdown
## 4. 파일별 발견 사항 (요약)

> 상세: [<topic>-per-file-findings.md](./docs/superpowers/specs/<topic>-per-file-findings.md)

| # | File | Findings | Critical | High | Medium | Low | 통과 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 4.1 | `feature-X.md` | 3 | 1 | 2 | 0 | 0 | N/A |
```

## §4-1. 적대 리뷰 결과 / Adversarial Review Results

§4 findings 5개 이상 시 `wiki-adversarial-reviewer` 디스패치 **권장**. 5개 미만이면 적대 리뷰 없이 송신 가능.

분할 시: 본 섹션은 **master report 에 들어간다**. per-file-findings 에는 들어가지 않는다.

### 4-1.1 적대 리뷰 실행 여부

| 항목 | 값 |
| --- | --- |
| 적대 리뷰 실행 | YES / NO |
| 실행하지 않은 사유 (NO 시) | <e.g., findings < 5> |
| 적대 리뷰 보고서 경로 | `docs/superpowers/specs/YYYY-MM-DD-<topic>-adversarial-review.md` |

### 4-1.2 적대 리뷰 요약 표 (실행 시)

| Finding ID | Original severity | Practicality | Overclaim | Assumption | Action |
| --- | --- | --- | --- | --- | --- |
| 4.1.1 | Critical | PASS | FAIL | PASS | DOWNGRADE → High |

### 4-1.3 컨트롤러 판단 반영

- **수용 (Accept)**: 권고대로 강등 또는 제거 적용.
- **거부 (Override)**: 거부 사유 1~2줄 명시 필수.

| Finding ID | 적대 권고 | 컨트롤러 결정 | 거부 사유 (Override 시) |
| --- | --- | --- | --- |
| 4.1.1 | DOWNGRADE → High | Accept | — |
| 4.2.1 | REJECT | Override (KEEP at Medium) | 사용자 환경에서 실제 관측 사례 |

### 4-1.4 결과 메트릭

- KEEP: <n>
- DOWNGRADE: <n>
- REJECT: <n>
- Override: <n>

§1 Executive Summary 와 §5 Priority Recommendations 는 적대 리뷰 결과 **반영 후** 상태. 강등된 finding 이 §5 에 여전히 Critical 이면 자동 `BLOCKED`.