7.8 KiB
Per-File Findings + Adversarial Review Template
Root SSOT: rules/reporting-standards.md §"4. 파일별 발견 사항" + §"4-1. 적대 리뷰 결과"
parent: README.md
§0~§3, §3-1 Verdict, §5~§8 → report-template.md
§7.1 self-grep 카운트 규칙 → 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 Contract 1 참조.
한 파일에서의 finding 개수
각 파일에 대해 분석이 surfacing 한 모든 gap 을 finding 으로 등재. 1 파일 = 1 finding 이 아니라 발견된 모든 결함·누락·모호점 빠짐없이 풀어쓴다. 보통 명세 1개 = 2~5 findings.
Single-finding Justification Gate
파일당 finding 이 정확히 1개라면 §4 하위섹션 끝에 반드시 정당화 블록 첨부. 정당화 없이 1개로 끝낸 파일은 자동 BLOCKED.
#### 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 파일은 하위섹션을 생략하지 않는다. 명시:
**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:
- 인용: "" (또는 "해당 라인 없음 — 명세 자체에 누락")
- 위치:
<path>:<line>
- 실무 가정 / Real-world assumptions (REQUIRED — min 1, typical 2~3):
비판이 성립하려면 어떤 실무 가정이 참이어야 하는가? 명시하지 않으면 비판은 "에이전트가 상상한 구현" 표적.
- 가정 A: <e.g., "구현이 동기식", "프로덕션 트래픽 > 1000 RPS", "K8s 환경">
- 무효 조건: <이 가정이 거짓일 시나리오>
- 사용자 검증 방법: <한 줄 체크>
- 가정 B: ...
- 가정 A: <e.g., "구현이 동기식", "프로덕션 트래픽 > 1000 RPS", "K8s 환경">
- 간극 / Gap (위 가정들이 모두 참일 때):
- 구체적 실패 모드: <X 상황에서 Y 발생 → Z 깨짐 — 1~3개>
- 재현 조건: <실패가 일어나는 트리거>
- 이 finding 이 무효해지는 경우: <어떤 가정이 거짓이면 비판 자체 사라지는가>
- 필요 조치: <구체 액션 — 추상 아닌 실행 가능 형태>
- 조치 근거: <왜 이 액션이 일반 대안보다 이 상황에 맞는가>
- 대안 / Alternatives considered:
../advisory-depth/contracts-2-3-4-structure.mdContract 2 — 가능한 모든 대안 열거 (3~5개)- 대안 A: <라벨> — 적용 상황 / 부적합 이유
- 대안 B: ...
- 대안 C (채택): <라벨> — 왜 이 상황에 가장 맞는가
- 반대 논거 / Counterarguments (REQUIRED — min 1, typical 2~3):
Contract 1 — 권고가 틀릴 수 있는 시나리오.
- 반대 A: <권고가 부적절·과잉인 시나리오>
- 반대 근거: <왜 그 시나리오에서 부적절한가>
- 검증 방법: <한 줄 체크>
- 반대 A: <권고가 부적절·과잉인 시나리오>
- 구현 단계: <순서 있는 단계>
- <단계 1 — 수정할 파일, 어디에 어떤 내용 들어가는지>
- <단계 2>
- 검증 방법:
- 자동: <self-grep /
wiki-link-verifier//lint/ frontmatter grep / wikilink ls 등> - 수동: <Obsidian 그래프뷰 / 리뷰 시 확인 포인트 — 자동 부족 시에만>
- 자동: <self-grep /
- 관련:
- 다른 finding 과 결합: <같은 / 다른 파일 finding 과 함께 처리해야 효과>
- 상호 의존 파일: <영향 주고받는 명세/모듈>
Finding 4.1.2: ...
4.2 <next filename> ...
NOT_READ 및 BLOCKED 파일은 본 섹션에 자기 하위섹션 X. 매트릭스와 §3 에만 등장.
Master report 에서의 §4 (분할 시)
분할 시 master report 의 §4 는 한 줄 요약 표만:
## 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:
- DOWNGRADE:
- REJECT:
- Override:
§1 Executive Summary 와 §5 Priority Recommendations 는 적대 리뷰 결과 반영 후 상태. 강등된 finding 이 §5 에 여전히 Critical 이면 자동 BLOCKED.