---
name: result-doc-writer
description: Write or update phase/session result documents (docs/sessions/phase-N/phase-N-result.md) and their todo mirrors (docs/planning/phase-N/phase-N-todo.md) in wikey's canonical structure. Use whenever the user asks to record a work result, add session findings, reorganize a result doc, regroup sections by subject, renumber headings to N/N.M, tag subjects with #category, or keep todo/result in sync. Triggers: "결과 기록", "activity 문서", "세션 정리", "phase result", "주제별로 묶어", "번호 체계 정리", "태그 추가", "result 문서 작성".
---

# Result Doc Writer — `docs/sessions/phase-N/phase-N-result.md` 작성 규칙

wikey 프로젝트에서 작업 결과를 `docs/sessions/phase-N/phase-N-result.md`에 기록하거나 재구성할 때 따를 원칙. 이 규칙은 사용자가 2026-04-20에 영구 고정한 것이며, CLAUDE.md 대신 이 스킬에서 관리한다.

## ⚠️ 전제 — 파일 명명규칙·조직화는 `CLAUDE.md §문서 명명규칙·조직화` 에서 관리 (2026-04-24)

본 스킬은 result **내용 작성 규칙** 만 담당. 보조 문서 파일명·디렉터리 배치·역참조 block·중심 문서 `관련 문서` 섹션 규칙은 프로젝트 rule (`CLAUDE.md`) 에 있다. 요약:

- 중심: `docs/sessions/phase-N/phase-N-result.md` · `docs/planning/phase-N/phase-N-todo.md`
- 보조 result: `docs/sessions/phase-N/phase-N-resultx-<section>-<topic>-<date>.md`
- 보조 plan: `docs/planning/phase-N/phase-N-todox-<section>-<topic>.md`
- `x` 접미사는 alphabet-sort 에서 중심 문서가 맨 앞에 오도록 하기 위함. `_` / `-` 금지.
- 모든 보조 문서는 타이틀 아래에 `> **상위 문서**: ...` 역참조 블록 유지.
- 중심 문서는 meta 블록 직후 `## 관련 문서` 섹션으로 보조 문서 전체를 section 번호 순 나열.

새 result 세션을 추가할 때 보조 측정·리포트를 분리 파일로 만들 가능성이 있다면 **파일명은 위 규칙 그대로** 생성해야 한다.

## ⚠️ 최우선 원칙 — **result 는 항상 상세하게** (2026-04-24 사용자 재강조)

> **"요약하지 않는다. 압축하지 않는다. 생략하지 않는다."**
>
> result 문서의 가치는 **그 당시 무엇이 일어났는지를 후일 라인 단위로 추적 가능** 하게 만드는 것이다. 세션 중 LLM이 "길어 보인다"는 이유로 자동 축약하거나 "이미 명확하니 생략"하는 것은 **가장 중대한 위반**이다.
>
> **판단 기준**: "6개월 뒤 다른 사람이 이 result 만 읽고 당시 작업을 재현·역추적할 수 있는가?" → No 면 부족. 수치·경로·커밋·원문 인용까지 다 남겨라.
>
> 긴 result 는 문제가 아니다. **짧은 result 가 문제**다. 재구성·정리 작업에서도 **내용을 줄이지 말고 구조만 재정렬**하라.

## 핵심 원칙 (3+1)

### 1. Subject에 의한 그룹화

최상위 섹션(`## N. 주제`)은 **작업 주제(기능·영역·범위) 단위**다. 시간이나 세션이 아니라 특성으로 묶는다.

예 — Phase 3 result에서 사용된 subject:
- `wikey-core 코어 구현`
- `Obsidian 플러그인 MVP`
- `UI/UX 고도화`
- `인제스트 파이프라인 v1~v6 + 3-stage 재설계`
- `스키마 안정화 + 결정성 측정 (v7 시리즈)`
- `문서 전처리 (PDF · OCR tier chain)`
- `프롬프트 시스템 (single prompt + override)`
- `로컬 LLM 모델 검증`
- `디버깅 · 운영 안정성`
- `E2E 자동 검증 + CDP`

피해야 할 패턴 — **세션/날짜 기반 subject**:
- ❌ `2026-04-19 저녁 세션`, `§C-2 정리 세션`, `Step 5 인제스트`
- 이런 건 subject가 아니라 subject 내부의 timeline entry 레이블로 쓴다.

### 2. 상세 타임라인에 의한 상세 기록 (**최우선**)

각 subject 내부(`### N.M`)는 진행 시간 순으로 기록하고, 각 항목은 **"이전 상태 → 작업 내용 → 결과 → 증거"**를 **빠짐없이** 담는다.

**반드시 포함해야 하는 구체 증거**:
- **수치** — CV %, 처리 시간 (ms/s), 토큰 수, 파일 크기 (bytes/lines), 테스트 수 (N/M passed), before/after 메트릭
- **커밋 해시** — 7자리 short hash (관련 커밋 **전부** 나열, 대표 1개가 아님)
- **파일 경로** — `wikey-core/src/schema.ts:42` 형식 (라인 번호 포함)
- **모듈·함수명** — `loadSchemaOverride`, `extractPdfText` (동사+객체 명시)
- **에러 메시지** — 원문 그대로 혹은 핵심 키워드 (요약 금지)
- **의사결정 근거** — "왜 A 대신 B 를 선택했는가" 의 정량·정성 근거
- **실패·롤백 경로** — 중간에 기각된 시도도 모두 기록 (차선책이 그대로 살아남는 경우가 있음)
- **시점** — 일자+시간대 가능하면 (`2026-04-23 23:49 ~ 00:48`)

**요약 금지 원칙**:
- "…" 으로 생략 금지. 긴 에러 스택은 관련 라인만 발췌하되 원문 인용 형식 유지 (```)
- "기타" 로 묶지 말 것. 5개 발견 사항이면 5개 모두 나열
- "등" 남용 금지. "A, B 등" 이 아니라 "A, B, C" 로 완전 나열
- Short summary 블록이 필요하면 상세 본문 **이후** 에 `### N.M.summary` 로 추가 (상세를 요약으로 대체 X)

Result 문서의 가치는 "그 당시 무엇이 일어났는지"를 나중에 추적할 수 있게 하는 데 있다. **긴 설명이 정리 대상 1순위가 아니다 — 오히려 긴 설명이 result 의 핵심 자산이다.**

### 3. 다른 주제 진행 중 이전 주제 관련 내용이 나오면 그 이전 subject의 타임라인 하단에 append

새 subject를 만들지 않는다.

예: 04-19 UI 재설계 세션에서 04-18 프롬프트 이슈의 후속 수정이 나오면 → **"프롬프트 시스템" subject의 타임라인 말미**에 `(2026-04-19 추가)` 라벨로 덧붙인다.

### 4. (파생) Todo와 Result의 관계

`docs/planning/phase-N/phase-N-todo.md`는 result의 subject 구조를 **1:1 미러하는 체크리스트**다.

- Subject 구성이 바뀌면 **result 먼저 고치고, todo가 그 구조를 따라간다**.
- Todo는 간결 (한 줄 체크박스), result는 상세.
- 대분류 #tag도 todo에 동일하게 반영한다.

## 번호 체계 (필수)

**Phase 번호를 맨 앞에 붙인 다계층 숫자만** 사용한다. Phase N의 문서라면:

| 레벨 | 형식 | 용도 | 마크다운 |
|------|------|------|---------|
| 작업 그룹 (top subject) | `N.1`, `N.2`, ... | 최상위 주제 | `## N.1 제목` + 다음 줄 `> tag: #t1, #t2` |
| 상세화 1단계 | `N.M.1`, `N.M.2`, ... | 주제 내 세부 | `### N.M.K 제목` |
| 상세화 2단계 | `N.M.K.1`, ... | 더 세부 | `#### N.M.K.L 제목` |
| 세부 task | `- [ ]` / `- [x]` | 실행 가능 단위 | 체크박스 목록 |

예 (Phase 4 todo):
```markdown
## 4.1 문서 전처리 파이프라인
> tag: #core, #workflow

### 4.1.1 Docling 통합 (Tier 1 메인)

#### 4.1.1.1 설치 경로 결정

- [ ] CLI (`uv tool install docling`) vs Python API 비교
- [ ] `extractPdfText` 체인 재정렬
```

- **이질 prefix 금지**: `Step N`, `Phase X-Y-Z`, `§A-N`, `(Must)`, `[v7-3]` 등을 섹션 헤더에 섞지 않는다.
- 본문 텍스트에서 커밋 컨벤션·히스토리 참조 용도로는 `v7-5`, `§C-2` 같은 히스토리 레퍼런스 표기를 그대로 사용해도 된다 — heading이 아니라 본문 참조로.
- result와 todo는 **동일한 `N.M / N.M.K / N.M.K.L` 번호**를 공유한다. todo는 체크박스, result는 상세 본문.

## 대분류 #tag (시스템 구성요소 관점)

각 subject(`## N.` 최상위 섹션)는 **제목 바로 다음 줄에 `> tag: #t1, #t2` 형식의 블록quote 라인**으로 대분류를 부착한다. 같은 subject가 여러 구성요소에 걸치면 콤마로 구분해 복수로 기재한다.

형식 규칙:
- `> tag: ` 접두사 뒤에 태그들을 콤마+공백으로 구분 (`> tag: #design, #workflow`)
- 제목 라인에는 `#tag` 를 **붙이지 않는다** — 제목은 순수 텍스트만
- 태그 라인 다음은 빈 줄 하나, 그 아래 본문

예:
```markdown
## 4.4 UI/UX 고도화
> tag: #design, #workflow

(본문 시작)

## 4.7 문서 전처리 (PDF · OCR tier chain)
> tag: #core, #workflow

## 4.9 로컬 LLM 모델 검증
> tag: #eval, #infra
```

### 허용 대분류 (필요시 확장)

| tag | 의미 |
|-----|------|
| `#architecture` | 시스템 구조, 계층, 디자인 결정 |
| `#framework` | 공통 기반 (schema, config, 타입·프로토콜) |
| `#core` / `#engine` | 핵심 로직 (LLM, canonicalizer, wiki-ops, query pipeline) |
| `#workflow` | 작업 흐름 (인제스트·쿼리·린트·분류·E2E) |
| `#main-feature` | 사용자에게 노출되는 주요 기능 단위 |
| `#design` | UI/UX, 시각·컴포넌트·테마 |
| `#utility` / `#helper` | 보조 도구, 스크립트, CLI 래퍼 |
| `#infra` | 배포·설정·CI·의존성 |
| `#ops` | 운영·디버깅·안정성·비용 추적 |
| `#eval` | 측정·벤치마크·결정성·성능 |
| `#docs` | 문서·스키마 변경·가이드 |

새 태그가 필요한데 목록에 없으면 이 목록에 먼저 추가한 뒤 사용한다.

## 자동화 툴

`result + todo`를 주제별로 재구성해야 할 때 참고할 수 있는 기존 아티팩트:

- 이번 Phase 1/2/3 재구성에 사용된 Python 스크립트 패턴 — 섹션 atom 추출 → theme classify → 새 번호 부여.
- 본 스킬은 규칙만 정의하며, 자동화가 필요하면 Python·Bash로 생성·반복 실행 가능.

## 문서 레이아웃 체크리스트

새 result 파일을 작성할 때:

1. 최상단 meta 블록 (기간, 상태, 전제, 인프라, 참조 파일)
2. `---` 구분선
3. 첫 subject는 보통 `## 1.1 개요 및 타임라인` + 다음 줄 `> tag: #docs, #architecture`
4. 이후 subject들 (`## 1.2` ~ `## 1.N` 또는 Phase 번호에 맞춰 `## N.M`)은 위 원칙에 따라 주제별
5. 마지막 subject는 "Phase X 완료 체크리스트" 또는 "다음 Phase 준비 상태" 또는 "Phase N+1 이관 + 종료 선언" 중 해당 상황에 맞게

## 대응되는 todo 파일 체크리스트

`docs/planning/phase-N/phase-N-todo.md`:

1. meta 블록 (result와 동일하되 "번호 계층·mirror" 안내 포함)
2. `---`
3. `## N.M 제목` + 다음 줄 `> tag: #t1, #t2` — result와 동일한 번호·제목·태그
4. 하위 `- [x] N.M 한 줄 요약`으로 체크박스 리스트
5. 완료 안 된 항목은 `- [ ]` 또는 `- [~]`(진행 중)로 구분

## Anti-patterns (하지 말 것)

- ❌ result를 축약·요약한다 — **내용 보존이 최상위 가치**
- ❌ subject를 세션/날짜 이름으로 만든다
- ❌ `Step 1-2-A`, `§B-2 #4` 같은 prefix를 heading에 남긴다
- ❌ 같은 번호(`## 3`)를 두 번 쓴다 (시간순 추가의 부작용)
- ❌ CLAUDE.md 또는 글로벌 메모리에 이 규칙을 중복 기록 — 이 스킬이 단일 소스