feat: 공식 문서 근거자료, 브랜치 기능 문서 작성
This commit is contained in:
DongHyeonka
@@ -0,0 +1,158 @@
|
||||
# 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 명시 |
|
||||
Reference in New Issue
Block a user