Imported from woosul/wikey (.claude/skills/result-doc-writer/SKILL.md). Install upstream with npx skills add woosul/wikey --skill result-doc-writer. Copyright stays with the author.

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의 문서라면:

예 (Phase 4 todo):

## 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 를 붙이지 않는다 — 제목은 순수 텍스트만
• 태그 라인 다음은 빈 줄 하나, 그 아래 본문

예:

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

(본문 시작)

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

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

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

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

자동화 툴

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 또는 글로벌 메모리에 이 규칙을 중복 기록 — 이 스킬이 단일 소스