llm-wiki/.agents/workflows/ingest.md

description

description
raw 자료를 wiki 문서로 변환

사용자가 /ingest <raw 경로 또는 자료 설명> 를 입력하면 아래 절차를 수행한다.

다음 raw 자료를 wiki 문서로 변환합니다.

대상: <raw 경로 또는 자료 설명>

작업 절차

1. source_type 분류 (CLAUDE.md §5 와 일치, templates 와 1:1)

   • official-doc / company-tech-blog / personal-blog / lecture / project-note / error-note / job-posting / blog-topic / interview-prep / daily-note / branch-note / concept / interview / portfolio / blog / llm-generated
   • deprecated 표기 거부: error-log → error-note, interview-note → interview-prep, lecture-note → lecture. 입력이 deprecated 면 정정 후 진행.
   • daily-note, branch-note는 "특수" 처리 절차(아래)로 분기됨.

2. 핵심 개념 추출

   • 자료가 다루는 주요 개념 1–5개 식별
   • raw source 의 Claims Extracted 와 branch-note 의 Decision Evidence Map 을 먼저 확인
   • 근거 Claim 이 없는 단정은 wiki FACT 로 승격하지 않음 (INFERENCE 또는 needs-confirmation)

3. wiki 위치 결정 (canonical만)

   • 일반 개념 → wiki/concepts/<concept-slug>.md (평면)
   • 내 프로젝트 사실 → wiki/projects/<project-slug>/<topic>.md (nested — rules/naming-conventions.md §2.11). 새 프로젝트면 sibling named hub wiki/projects/<project-slug>.md (MOC) 도 함께 생성 (folder-note 패턴, index.md 사용 금지 — rules/linking-rules.md §12).
   • 금지: wiki/interview/, wiki/portfolio/, wiki/blog/. /ingest는 canonical만 생성.
   • 자료 안에 면접·포트폴리오·블로그로 옮길 만한 부분이 있어도 먼저 canonical로 변환한 뒤, 별도로 /interviewize / /blogify 또는 수동 작성 단계로 진행.
   • raw/blog-topics/는 블로그 글감 원석이며, /ingest는 여기서 바로 wiki/blog/를 만들지 않는다. promotable claim만 canonical 후보로 정제한다.

4. 템플릿 적용 (canonical 출력 + raw 보관용만)

   • 개념 (wiki/concepts/): templates/concept-template.md
   • 프로젝트 (wiki/projects/): templates/wiki-project-template.md
   • 외부 자료 원본 발췌 (raw/): templates/raw-source-template.md
   • 외부 자료 검증된 요약 (wiki/concepts/): templates/source-summary-template.md
   • templates/interview-template.md은 /interviewize 전용. /ingest는 사용하지 않음.

5. YAML frontmatter 작성

   • CLAUDE.md 메타데이터 표준 준수 (title, source_type, status, confidence, tags, related_projects, last_reviewed)
   • last_reviewed는 오늘 날짜로

6. 링크 연결

   • 관련 문서는 [[wikilink]]로 양방향 연결
   • 원본 raw 문서를 Sources에 명시

7. 원본 보존 확인

   • 외부 URL이 있으면 raw 문서에 핵심 인용 3–5문장이 발췌되어 있는지 확인
   • 누락이면 발췌 후 raw에 추가
   • 가능하면 archive_url 병기

8. Hub 및 log 갱신

   • wiki/llm-wiki.md (vault MOC) 에 새 카테고리 / 허브 문서가 추가되었으면 업데이트 (개별 문서 일일이 나열 X)
   • wiki/log.md에 한 줄 기록: YYYY-MM-DD HH:mm /ingest — <raw 경로> → <wiki 경로>

규칙

• 프로젝트 관련 진술은 반드시 증거 등급(actually-implemented / locally-verified / prod-verified / documented-only / planned / needs-confirmation) 명시.
• 공식 문서와 기술블로그 혼동 금지. 기술블로그는 사례, 공식 best practice가 아님.
• Claim ID 없는 결정 승격 금지. branch-note 의 결정은 Supporting Claims 가 있거나 UNSUPPORTED_DECISION 으로 명시된 상태여야 한다.
• LLM 생성 내용은 confidence: high로 두지 말 것. 최대 medium.
• 원본을 임의로 의역하지 말 것. 인용은 인용 표시(>)로 분리.
• 모호하면 status: needs-confirmation으로 두고 사람 검토 대기.

특수: daily-note 처리

source_type: daily-note 또는 raw/daily-notes/ 하위 파일을 ingest할 때:

• 원본 daily 파일을 wiki로 통째 옮기지 않음. raw에 영구 보관.
• 파일 내 섹션별로 promotable 항목만 추출. canonical(wiki/concepts/, wiki/projects/)으로만 추출. 파생 산출물 직접 생성 금지.
  • 한 일 / 트러블슈팅 → 관련 wiki/projects/에 추가 또는 신규 생성 (증거 등급 표기 필수). [branch-name] 프리픽스가 있으면 해당 브랜치 노트의 "마주친 문제"·"진행 중 메모"에도 cross-link.
  • 배운 점 → wiki/concepts/에 신규/추가
  • 트러블슈팅 중 재발 가능한 패턴 → wiki/concepts/로 (raw/errors/는 원본 보관 위치, 변환 X)
  • 면접·포트폴리오 옮길 만한 것 → 후보 표기만. 관련 wiki/projects/ 문서의 "면접 후보" 메모 또는 frontmatter 태그로 표시. wiki/interview/·wiki/portfolio/ 문서를 직접 만들지 않음 — 후속 /interviewize 또는 수동 작성 단계로 위임.
  • 잡담 / 회의 / 기타 → 추출하지 않음 (raw에만 남김)
• 추출 시 daily 파일 경로를 새 wiki 문서의 Sources에 [[raw/daily-notes/YYYY-MM-DD]] 형식으로 링크.
• 추출하지 않은 항목은 daily 파일에 그대로 둠 (수정·삭제 금지).

특수: branch-note 처리

source_type: branch-note 또는 raw/branch-notes/ 하위 파일을 ingest할 때:

• 원본 branch 파일을 wiki로 통째 옮기지 않음. raw에 영구 보관 (머지 후에도).
• 추출 트리거: status_label이 merged 또는 abandoned 또는 완료 후 정리 섹션이 채워졌을 때.
• 섹션별 처리 (canonical로만 추출, 파생 산출물 직접 생성 금지):
  • 완료 후 정리 → wiki 추출 대상 의 actually-implemented / locally-verified / prod-verified 항목만 wiki/projects/로 추출 (신규 또는 기존 project 문서에 추가). 다른 등급은 추출 금지.
  • 결정 사항 (decisions) → 추출된 wiki/projects/ 문서의 "결정 이유" 섹션에 통합. 면접 후보면 frontmatter 태그(interview-candidate)만 표시. wiki/interview/ 직접 생성 금지 — 후속 /interviewize 단계로 위임.
    • 단, Decision Evidence Map 에서 Claim ID 로 뒷받침되는 결정만 FACT 로 통합. UNSUPPORTED_DECISION 은 추출하지 않고 검증 필요로 남김.
  • 마주친 문제 중 해결된 패턴 → wiki/concepts/ 후보로 보고. 사용자 확인 후 변환.
  • TODO 중 abandoned/planned → 추출하지 않음. branch-note에만 기록 남김.
  • 목표 / 범위 / 진행 중 메모 / 잡담 → 추출하지 않음.
• 추출한 wiki 문서의 Sources에 [[raw/branch-notes/<branch-name>]] cross-link.
• 추출 후 branch-note의 status_label을 merged로 갱신 가능 (사용자 확인 후).
• abandoned 브랜치는 추출 없이 raw에만 보관. 단, 결정 사항/마주친 문제는 회고·면접에서 "왜 폐기됐나" 근거가 되므로 삭제 금지.

출력: Stats funnel (no-silent-truncation)

작업 종료 시 ## Stats 절을 보고한다 (rules/reporting-standards.md No silent truncation 계약):

## Stats
found: <식별한 promotable 항목 수>
processed: <canonical 로 promote 한 수>
dropped: <추출 안 한 수>
dropped_reason: <항목별 제외 사유 (raw 보존 / 잡담 / abandoned / planned 등)>

found = processed + dropped 균형 필수. daily/branch 특수처리에서 "추출 안 함" 으로 raw 에 남긴 항목도 dropped 에 카운트하고 사유를 적는다 — 무엇을 안 옮겼는지 보이게. 침묵 누락 금지.