# Report Template (§0~§3, §3-1 Verdict, §5~§8)

Root SSOT: [`rules/reporting-standards.md`](../../../../../rules/reporting-standards.md) §"Report Template"
parent: [`README.md`](README.md)

§4 Per-File Findings + §4-1 Adversarial Review → [`findings-template.md`](findings-template.md)
§7 Verification (self-grep 카운트 규칙) → [`verification-rules.md`](verification-rules.md)

모든 covered 보고서는 본 섹션 순서를 따른다. 재정렬 / 병합 / 생략 금지. 빈 섹션은 `해당 없음 / N/A` 로 명시.

## Frontmatter

```markdown
# [작업명] 보고서

**일자 / Date:** YYYY-MM-DD
**범위 / Scope:** <N개 파일 또는 영역>
**Verdict:** COMPLETE | PARTIAL | BLOCKED
**요청 언어 / User language:** ko | en | mixed
```

## §0. Source roots (외부 디렉토리 참조 시에만)

| Alias | 절대 경로 |
| --- | --- |
| `<raw-branches>` | `/home/donghyeon/Documents/LLM Wiki/raw/branch-notes` |
| `<raw-projects>` | `/home/donghyeon/Documents/LLM Wiki/raw/project-notes` |
| `<wiki-concepts>` | `/home/donghyeon/Documents/LLM Wiki/wiki/concepts` |
| `<wiki-projects>` | `/home/donghyeon/Documents/LLM Wiki/wiki/projects` |
| `<ca-tmpl>` | `/home/donghyeon/workspace/ca-tmpl` (코드 컨텍스트 참조 시) |

이후 인용 예: `<raw-branches>/feature-X.md:42`. 워크스페이스 안만 다루면 "해당 없음 / N/A".

## §1. 한눈 요약 / Executive Summary

3~6 문장. 무엇을 했는가 / 정독 파일 수 vs 전체 in-scope / 가장 중요한 발견 1~2 / 후속 조치 필요 항목 수.

## §2. Evidence Matrix

### Evidence Matrix Hard Format

Rows must be mechanically countable by the hook. Use exactly:

```text
| Path | Status | Evidence | Extracted facts |
| --- | --- | --- | --- |
| raw/branch-notes/<file>.md | READ_FULL | lines x-y | <fact> |
```

Do not use filename-only paths (`feature-x.md`), `Status=raw`, or `READ_FULL=Yes`. Allowed status values are exactly `READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED`.


모든 in-scope 파일에 정확히 한 행. 누락 금지.

| Path | Status | Evidence | Extracted facts |
| --- | --- | --- | --- |
| <path> | READ_FULL | <line range> | <facts in user language> |
| <path> | NOT_READ | <reason> | UNVERIFIED |

allowed Status: `READ_FULL`, `READ_PARTIAL`, `NOT_READ`, `BLOCKED`.

## §3. 커버리지 정합성 / Coverage Reconciliation

본 섹션은 자기 신고 아닌 **산식 영역**.

| 항목 | 값 |
| --- | --- |
| (a) in-scope 파일 수 | <N> |
| (b) §2 evidence matrix 총 행 수 | <M> |
| (c) §2 의 `READ_FULL` + `READ_PARTIAL` 행 수 | <R> |
| (d) §4 deep-template 충족 하위섹션 수 | <P> |
| (e) (a − b) — 매트릭스 누락 | <a-b> |
| (f) **(c − d) — 분석 깊이 미달** | **<c-d>** |

### 분석 깊이 미달 파일 명세

`(c − d) > 0` 이면 누락 파일 빠짐없이 나열. "없음" 적었으나 누락 있으면 자동 `BLOCKED`.

| 파일 경로 | §2 Status | §4 분석 여부 | 누락 사유 |
| --- | --- | --- | --- |

(비어 있으면 명시: "분석 깊이 미달 없음 — (c − d) = 0".)

### `NOT_READ` / `BLOCKED` 파일

- `NOT_READ` 목록: <list 또는 "없음">
- `BLOCKED` 목록 (사유): <list 또는 "없음">

### 정직성 컨트랙트

- 모든 사실 주장은 §2 매트릭스의 `READ_FULL` / `READ_PARTIAL` 행에서 나옴
- §4 미다룸 파일은 §5 등장 불가
- 매트릭스 vs §4 행 수 불일치 시 §5 에 §4 없는 파일 올리면 자동 `BLOCKED`

## §3-1. Verdict 결정 알고리즘 / Verdict Calculation

**산식이 라벨을 결정**. agent 가 자기 의지로 라벨링 X. 산식과 라벨 불일치 시 송신 불가.

```text
Let:
  N = in-scope 파일 수
  M = §2 evidence matrix 총 행 수
  R = §2 의 READ_FULL + READ_PARTIAL 행 수
  P = §4 deep-template 충족 하위섹션 수
  G = self-grep 검증 (verification-rules.md) 통과 finding 수
  T = 전체 finding 수

Verdict =
  COMPLETE  iff (M == N) AND (P == R) AND (G == T) AND (모든 §5 권고가 §4 파일을 가리킴)
  PARTIAL   iff (M == N) AND ((P < R) OR (G < T))
  BLOCKED   iff (M < N) OR (enumeration 불가) OR (필수 first reads 차단)
```

`COMPLETE` 적으려면 4개 조건 **전부 참**. 하나라도 거짓 → 자동 `PARTIAL` 또는 `BLOCKED`.

Pre-send 시 §3 (a)~(f) 값을 실제 계산 → 산식 평가 → Verdict 라벨 채움. 산식 위반은 정직성 실패, draft 폐기.

## §4 + §4-1

→ [`findings-template.md`](findings-template.md) 별도 sub-file. Per-File Findings deep template + Single-finding gate + Zero-finding handling + Adversarial Review.

## §5. 우선순위 권고 / Priority Recommendations

| 우선순위 | 권고 액션 | 근거 파일:라인 | 원래 목표 | 현재 간극 | 조치 후 효과 |
| --- | --- | --- | --- | --- | --- |
| 1 (Critical) | ... | `<file:line>` | ... | ... | ... |
| 2 (High) | ... | `<file:line>` | ... | ... | ... |

각 행은 §4 의 한 Finding 과 **1:1 대응**. 단순화 / 축약 / 일반화 금지. 본 표 모든 파일은 §4 에 자기 하위섹션 보유 필수. §4 에 없는 파일을 본 표에 올리면 자동 `BLOCKED`.

## §6. 후속 작업 / Follow-Up

- 다음 라운드 정독 대상 파일
- 미해결 위험
- 추가 검증 필요한 가설
- Out of scope: <slice 가 다루지 못한 인접 영역>

## §7. 검증 / Verification

→ [`verification-rules.md`](verification-rules.md) — §7.1 self-grep proof + §7.2 실행 명령 + 카운트 규칙.

## §8. Generated Artifacts (분할 시에만)

- 전체 보고서: `docs/superpowers/specs/YYYY-MM-DD-<topic>-report.md`
- 파일별 상세: `docs/superpowers/specs/YYYY-MM-DD-<topic>-per-file-findings.md`
- 작성 일자: YYYY-MM-DD
- 작성 도구: Antigravity CLI / wiki-superpowers plugin

## Anti-Patterns to Avoid

| Pattern | Why fails | Replacement |
| --- | --- | --- |
| "Pillar A: 4 files" 묶음 비평 | 4개 중 어느 파일 어디서 나온 사실인지 추적 불가 | 파일당 §4 하위섹션 1개 |
| GitHub `[!WARNING]` admonition만 | 출처 사라짐. 인용 라인 없음 | `<file:line>` 인용 + 한 줄 발췌 |
| 영어 보고서 + 한국어 대화 | 사용자가 번역 강요됨 | 사용자 언어로 통일 |
| Executive summary 없이 본론 | 핵심을 끝까지 읽어야 알 수 있음 | §1 3~6 문장 |
| 우선순위 표에 정독 안 한 파일 | 추측을 권고로 둔갑 | §4 에 있는 파일만 §5 |
| Verdict 없이 발견만 나열 | 통과/실패 판단 불가 | 상단 frontmatter Verdict 명시 |