llm-wiki/.agents/workflows/migrate-claims.md

description

description
기존 raw/source/branch/wiki 문서를 Claim ID 기반 template 구조로 단계적 마이그레이션

사용자가 /migrate-claims <scope: all | raw-sources | branch-notes | wiki-concepts | path> 를 입력하면 아래 절차를 수행한다.

기존 문서를 Claim Traceability 구조로 마이그레이션합니다.

대상: <scope: all | raw-sources | branch-notes | wiki-concepts | path>

원칙

이 명령은 좋은 마이그레이션 순서를 강제합니다. 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를 안정적으로 부여합니다.
   • 형식: <SOURCE-SLUG-UPPER>-C<number>
   • 예: 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<number> 또는 <BRANCH-SLUG-UPPER>-D<number>
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

최종 보고 전 다음을 기계적으로 계측합니다.

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 없이 완료 보고 금지