--- description: "기존 raw/source/branch/wiki 문서를 Claim ID 기반 template 구조로 단계적 마이그레이션" --- 사용자가 `/migrate-claims ` 를 입력하면 아래 절차를 수행한다. 기존 문서를 Claim Traceability 구조로 마이그레이션합니다. **대상:** ## 원칙 이 명령은 좋은 마이그레이션 순서를 강제합니다. branch-note를 먼저 고치지 않습니다. 먼저 source claim을 만들고, 그 다음 branch decision을 연결하고, 마지막에 wiki FACT를 승격합니다. ## Phase 0 — Scope Inventory 1. 대상 scope를 확정합니다. - `all`: `raw/official-docs/`, `raw/company-tech-blogs/`, `raw/branch-notes/`, `wiki/concepts/` - `raw-sources`: `raw/official-docs/`, `raw/company-tech-blogs/` - `branch-notes`: `raw/branch-notes/` - `wiki-concepts`: `wiki/concepts/` - 특정 path: 해당 파일 또는 디렉터리 2. 파일 목록을 정렬합니다. 3. Evidence Matrix를 먼저 만듭니다. 4. 10개 초과 파일이면 `wiki-research-lane` 또는 병렬 subagent slice로 나눕니다. ## Phase 1 — Raw Source Claim Migration 대상: `raw/official-docs/`, `raw/company-tech-blogs/` 각 파일에 대해: 1. 기존 본문을 삭제하지 않습니다. 2. `templates/raw-source-template.md`를 기준으로 누락 섹션만 보강합니다. 3. `## 핵심 인용` 또는 기존 quote/summary를 읽고 `## Claims Extracted`를 작성합니다. 4. Claim ID를 안정적으로 부여합니다. - 형식: `-C` - 예: `KEYCLOAK-OIDC-C1`, `STRIPE-IDEMP-C2` 5. `Strength`를 보수적으로 지정합니다. - official docs: `official-standard`, `official-vendor-doc`, `official-reference` - company blog: 기본 `company-case-study` - 불확실하면 `needs-confirmation` 6. `Does not prove`와 `Usage Boundaries`를 반드시 채웁니다. 7. 원문 quote가 있으면 `grep -nF` 또는 `sed -n` proof를 남깁니다. 완료 조건: - 모든 source 문서에 `## Claims Extracted` 존재 - 모든 Claim row에 `Claim ID`, `Claim`, `Evidence quote`, `Strength`, `Applies to`, `Does not prove` 존재 - 회사 블로그 Claim을 공식 best practice로 승격하지 않음 ## Phase 2 — Branch Decision Mapping 대상: `raw/branch-notes/` Phase 1이 끝나지 않았으면 BLOCKED입니다. branch-note는 source Claim ID 없이는 정상 마이그레이션할 수 없습니다. 각 파일에 대해: 1. 기존 `## 결정 사항`, `## Sources / 근거`, `완료 후 정리`를 읽습니다. 2. 중요한 구현 결정을 `Decision ID`로 분리합니다. - 형식: `D` 또는 `-D` 3. `## Decision Evidence Map`에 결정별 Supporting Claims를 연결합니다. 4. 연결 가능한 Claim이 없으면 추측하지 않고 `UNSUPPORTED_DECISION`으로 둡니다. 5. 확인해야 할 내용은 `## Claims To Verify`에 남깁니다. 완료 조건: - 모든 branch-note에 `## Decision Evidence Map` 존재 - 모든 중요한 decision은 Claim ID 또는 `UNSUPPORTED_DECISION`으로 분류 - 존재하지 않는 Claim ID 참조 없음 (`BROKEN_CLAIM_REFERENCE` 0) ## Phase 3 — Wiki Concept / Project Promotion Check 대상: `wiki/concepts/`, 필요 시 `wiki/projects/` 1. `## Claim-backed Knowledge`를 추가합니다. 2. source Claim 또는 branch Decision으로 뒷받침되는 내용만 `FACT`로 둡니다. 3. 근거가 약한 설명은 `INFERENCE`, `needs-confirmation`으로 낮춥니다. 4. 회사 기술 블로그 단독 근거는 case-study로 표현합니다. 완료 조건: - wiki FACT는 Supporting Claims를 가짐 - unsupported decision이 wiki FACT로 승격되지 않음 ## Phase 4 — Controller Verification 최종 보고 전 다음을 기계적으로 계측합니다. ```bash find raw/official-docs raw/company-tech-blogs -maxdepth 1 -type f -name '*.md' | sort # 미마이그레이션 파일 목록 (주의: rg 의 -L 은 --follow 다 — files-without-match 는 긴 플래그만 존재) rg --files-without-match '^## Claims Extracted' raw/official-docs raw/company-tech-blogs rg --files-without-match '^## Decision Evidence Map' raw/branch-notes rg -n 'UNSUPPORTED_DECISION|BROKEN_CLAIM_REFERENCE|MISSING_CLAIMS_EXTRACTED' raw wiki docs ``` 보고서에는 반드시 다음을 포함합니다. | Metric | Expected | Actual | Status | |---|---:|---:|---| | Raw source files with Claims Extracted | N | M | PASS/FAIL | | Branch notes with Decision Evidence Map | N | M | PASS/FAIL | | Broken Claim references | 0 | B | PASS/FAIL | | Unsupported decisions | report count | U | INFO | ## Verdict Rules - `COMPLETE`: Phase 1~4 완료, missing required sections 0, broken references 0 - `PARTIAL`: 지정 scope 내부는 완료했지만 전체 corpus가 아님 - `BLOCKED`: source Claim migration 없이 branch-note mapping을 시도했거나, unread files가 있음 ## 금지 - source Claim 없이 branch decision을 임의로 official-supported 처리 금지 - 회사 기술 블로그만 보고 universal best practice라고 작성 금지 - 기존 본문 삭제/요약으로 손실 발생 금지 - 여러 파일을 처리하면서 Evidence Matrix 없이 완료 보고 금지