wiki-update

name	wiki-update
description	InnoLive 팀 LLM 위키(framework-llm-wiki)에 세션에서 얻은 사실을 반영하고 PR까지 올린다. 파일을 고치기 전에 변경 계획을 표로 제시해 승인을 받고, 승인된 항목만 수정한다. 사용자가 "위키 업데이트", "위키에 남겨줘", "위키에 반영해줘", "이거 문서화해줘"라고 하거나 작업을 마치고 기록을 남길 때 사용한다. 코드 레포(innolive-server, innolive-ai, innolive-client)에서 작업하다가 그 결과를 위키에 남길 때가 주 사용 상황이다. 위키를 읽거나 검색만 할 때는 사용하지 말 것 - 그때는 framework-wiki MCP 도구를 직접 쓴다. 코드 레포에 파일을 쓰는 작업에도 쓰지 말 것 - 이 스킬은 위키 레포에만 쓴다.
license	팀 내부용
metadata	{"version":"0.8.0","owner":"server-team","repo":"team-framework/framework-llm-wiki","mcp-server":"framework-wiki"}

Wiki Update

InnoLive 팀 LLM 위키에 세션 산출물을 반영하고 PR을 올린다.

Critical rules

이 넷은 절대 어기지 않는다.

1. 승인 없이 파일을 수정하지 않는다. Step 4에서 변경 계획을 제시하고, 승인된 항목만 고친다.
2. 원격에 올리기 전에 한 번 더 확인받고, 머지하지 않는다. push·PR 직전에 커밋을 보여주고 묻는다(Step 7). PR URL을 보고한 뒤 멈춘다.
3. 위키 레포에만 파일을 쓴다. innolive-server·innolive-ai·innolive-client에는 쓰지 않는다. 그 레포에서 작업하다 위키에 남기는 것은 정상 사용이며, 쓰기 대상만 위키로 한정한다는 뜻이다.
4. 사실 조회는 MCP로 한다. 로컬 클론은 쓰기 대상이지 읽기 소스가 아니다. 브랜치에서 작업 중인 상태를 현행으로 착각하게 된다.

사용하는 MCP 도구

framework-wiki MCP 서버가 붙어 있어야 한다. 네 개 전부 읽기 전용이며, 쓰기는 로컬 Git으로만 한다.

도구	언제
mcp__framework-wiki__get_wiki_status	Step 1 — 색인 상태 확인
mcp__framework-wiki__search_wiki	Step 3 — 대상 문서 탐색
mcp__framework-wiki__read_note	Step 3 — 후보 문서 정독
mcp__framework-wiki__get_current_metrics	변동 수치를 다룰 때 (_현행_수치.md 전용 창구)

Instructions

Step 0: 클론 경로 확인

사용자에게 묻는다:

"클론해두신 framework-llm-wiki 경로를 알려주세요."

세션 내 첫 발동 때만 묻고, 이후에는 받은 경로를 재사용한다. 아래에서 WIKI는 그 경로다.

받으면 세 가지를 검증한다.

git -C "$WIKI" rev-parse --git-dir      # 클론인가
git -C "$WIKI" remote get-url origin    # framework-llm-wiki 인가
git -C "$WIKI" status --porcelain       # 비어 있어야 함

• rev-parse가 실패하면 그건 클론이 아니라 복사본이다. 중단한다. 커밋할 수 없다.
• remote가 framework-llm-wiki가 아니면 중단하고 경로를 다시 묻는다.
• status가 비어 있지 않으면 아래 "워킹트리가 더러울 때" 로 간다.

워킹트리가 더러울 때

CRITICAL: 이 변경이 누구 것인지 에이전트가 판정하지 않는다. 상태를 전부 보여주고 사용자가 정한다.

브랜치 이름으로 추정하지 말 것. GITHUB_ID/작업명은 팀 브랜치 규칙 그 자체라 팀원이 손으로 만든 브랜치도 같은 형태이고, 반대로 이 스킬이 Step 5~6에서 죽었으면 브랜치는 아직 main이다(브랜치는 Step 7에서야 생긴다).

상태 넷을 그대로 제시한다.

git -C "$WIKI" branch --show-current       # 현재 브랜치
git -C "$WIKI" status --short -uall        # 변경 목록 (?? = 추적되지 않는 새 파일)
git -C "$WIKI" log --oneline main..HEAD    # 커밋 여부 (main에 있으면 빈 출력이 정상)
git -C "$WIKI" diff HEAD --stat            # 변경 규모 (staged 포함)

-uall을 빼면 새 폴더가 ?? 지식베이스/ 한 줄로 접혀 안에 몇 개가 들었는지 보이지 않는다. diff에 HEAD를 빼면 staged 변경이 안 보인다 — Step 7의 add와 commit 사이에서 죽으면 그 상태가 된다.

읽는 법 — 판정이 아니라 힌트다. 어느 쪽인지는 사용자만 안다.

관측	시사하는 것
브랜치가 main인데 변경이 있음	이 스킬이 Step 5~6에서 죽었을 가능성
브랜치가 GITHUB_ID/...	이 스킬의 잔재일 수도, 팀원이 직접 만든 브랜치일 수도 있다
??로 시작하는 줄	신규 문서를 만들다 멈춘 흔적

이 상태를 보여주고 어느 쪽인지 묻는다. 셋 중 하나를 고르게 한다.

선택	처리
이어서 작업	아래 "이어서 작업"
버리고 새로 시작	아래 "버리고 새로 시작"
사람이 직접 정리	중단하고 상태만 보고한다

이어서 작업

1. 이미 바뀐 내용을 먼저 승인받는다.

git -C "$WIKI" diff HEAD              # 추적 파일의 변경 내용 (staged 포함)
git -C "$WIKI" status --short -uall   # 신규 파일 목록

HEAD를 빼면 staged 변경이 빠져 빈 diff가 나온다. 그 화면으로 승인을 받으면 사용자는 변경이 없다고 오인한다 — 이 게이트가 가장 필요한 상황에서 무력화된다.

CRITICAL: 이 변경은 이전 실행이 다른 계획으로 승인받은 것이고, 그 계획을 지금은 모른다. 승인 없이 이어가면 Critical rules 1번이 재시작 경로에서 무너진다. 사용자가 남길 것과 되돌릴 것을 고른 뒤에 진행한다. 되돌릴 파일은 git -C "$WIKI" restore --staged --worktree 파일경로.

2. get_wiki_status로 색인을 대조한다 (Step 1 후반부). 건너뛰지 않는다 — 이어서 작업하는 상황은 정의상 시간이 지난 뒤라 색인이 더 어긋나 있다.

3. switch main과 pull --ff-only는 건너뛴다. 브랜치 작업 중 main을 당기면 헛일이다.

4. Step 2로 진행한다.

버리고 새로 시작

CRITICAL: 순서가 중요하다. switch를 먼저 하면 잔여 변경 때문에 실패한다 — error: Your local changes to the following files would be overwritten by checkout.

# 1. 추적 파일의 변경부터 되돌린다 (인덱스 + 워킹트리 양쪽)
git -C "$WIKI" restore --staged --worktree .

# 2. ?? 항목이 있으면 — 지울 목록을 먼저 보여주고 확인받는다
git -C "$WIKI" status --short -uall    # 지워질 파일을 하나씩. -uall 없으면 폴더로 접힌다
git -C "$WIKI" clean -nd               # dry run. 위와 함께 사용자에게 보여준다
git -C "$WIKI" clean -fd               # 확인받은 뒤에만

# 3. 브랜치를 옮기고 지운다 (main이 아니었을 때만)
git -C "$WIKI" switch main
git -C "$WIKI" branch -D 브랜치명

# 4. 잠금이 실제로 풀렸는지 확인 — 빈 출력이어야 한다
git -C "$WIKI" status --porcelain

• --staged가 빠지면 안 풀린다. restore .는 기본이 --worktree라 인덱스를 건드리지 않는다. Step 7의 add와 commit 사이에서 죽었다면 M ·A 가 그대로 남고, A 신규 파일은 이미 추적 대상이라 clean -fd도 지우지 못한다. 양쪽을 함께 줘야 신규 파일이 ??로 내려와 다음 clean이 처리한다.
• restore만으로도 부족하다. 추적되지 않는 파일은 남아서 status --porcelain이 계속 ??로 잡는다. 이 스킬은 신규 문서 생성이 정상 경로라 흔한 경우다.
• clean -fd는 되돌릴 수 없다. 반드시 목록을 보여주고 확인받는다. clean -nd와 status --short는 새 폴더를 한 줄로 접으므로(안에 50개가 있어도 ?? 지식베이스/) -uall을 함께 보여준다. 무관한 파일이 섞여 있으면 개별 경로로 지운다.
• 4번이 비어 있지 않으면 진행하지 말고 보고한다.

Step 1: main 최신화와 색인 대조

git -C "$WIKI" switch main
git -C "$WIKI" pull --ff-only origin main

--ff-only가 실패하면 중단하고 알린다. 로컬에 갈라진 커밋이 있다는 뜻이며, 강행하면 남의 작업을 덮는다. reset --hard로 밀지 않는다.

이어서 MCP 색인 상태를 확인한다.

mcp__framework-wiki__get_wiki_status
  → { wiki_root, wiki_commit, note_count }

wiki_commit을 로컬 HEAD와 비교한다.

결과	뜻	조치
같음	MCP가 최신	그대로 진행
다름	MCP가 낡음	진행하되, 검색 결과에 최근 머지분이 빠져 있을 수 있음을 인지
null	서버가 커밋을 보고하지 못함	대조 불가. 로컬 pull 결과를 기준으로 삼고, 그 사실을 사용자에게 한 줄로 알린다

Step 2: 인입 판정

세션에서 나온 것을 다섯 갈래로 나눈다. 팀이 공유할 사실만 위키에 들어간다.

분류	판단 기준	처리
사실	코드·커밋·로그·실행으로 확인됨	위키에 서술
사실(과거)	지금은 아니지만 그때는 그랬음	[당시] 표기를 붙여 서술
가설	확인하지 못함	"미확인"으로 분리한다. 단정하지 않는다
할일	앞으로 할 일	위키에 넣지 않는다. 별도 채널로
개인 합의	사용자와 나 사이에서만 정한 규칙·판단 기준	아래 참조. 원칙적으로 적지 않는다

CRITICAL: 재현하거나 실행해보지 않은 것을 "확인됐다"로 쓰지 않는다. 근거가 코드 정독뿐이면 그렇게 적는다.

개인 합의를 규약처럼 적지 않는다

이건 참·거짓의 문제가 아니라 출처의 문제다. 세션에서 사용자와 정한 규칙은 그 자체로는 사실이지만 다른 팀원은 합의한 적이 없다. 위키에 들어가는 순간 팀 규약으로 읽히고, 다른 팀원의 에이전트가 그것을 근거로 판단한다.

• 이 세션의 작업 방식, 사용자가 나에게 준 지시, 둘 사이에서만 통하는 판단 기준은 적지 않는다.
• 애매하면 넣기 전에 묻는다. 담당자 한 명과 정한 것이 그 영역의 팀 결정인지 개인 합의인지는 사용자만 안다. 지레 판단해 넣지도, 지레 빼지도 않는다.
• 팀이 실제로 합의한 것은 verification: team-confirmed로 적는다. 근거를 댈 수 있으면 개인 합의가 아니다.

가늠자 한 줄: "다른 팀원이 이 문장을 처음 읽고 '나는 동의한 적 없는데'라고 할 수 있는가." 그렇다면 규약이 아니라 이 세션의 작업 방식이다.

작업 방식은 위키가 아니라 스킬에 담는다. 위키는 지식 저장소이지 에이전트 행동 규칙이나 작업 트래커가 아니다.

Step 6의 "개인 규칙" 검사는 여기서 놓친 것을 잡는 그물이다. 그물을 1차 방어선으로 쓰지 않는다 — 그때는 이미 파일에 쓴 뒤다.

Step 3: 대상 문서 확인

MCP로 찾는다. 로컬 grep보다 정확하다.

mcp__framework-wiki__search_wiki
  query: "핵심 키워드"
  limit: 5

반환값에 path · title · question · domain · owner · verification · last_verified · score · excerpt가 들어 있다. question과 excerpt만 봐도 병합 대상인지 대개 판단된다. 확실치 않을 때만 정독한다.

mcp__framework-wiki__read_note
  path: "지식베이스/성능·평가/04_미검증_항목_대장.md"

검색 옵션:

• domain — server / ai / client / product / shared 로 좁힌다
• verification — 특정 등급만 본다
• include_history — 기본 false. 과거 서술까지 봐야 할 때만 true

병합이 기본값이다. 기존 문서의 question과 겹치면 그 문서를 고친다. 신규 문서는 "기존 어느 문서의 질문에도 붙지 않는다"가 설명될 때만 만든다. 설명이 안 되면 만들지 않는다.

변동 수치(배포 태그·용량 등)를 다룬다면 여기서 mcp__framework-wiki__get_current_metrics로 현재 기록값을 확인한다.

Step 4: 변경 계획 제시 (승인 게이트)

표로 제시하고 멈춘다.

| # | 문서 | owner | 종류 | 내용 | 근거 |
|---|---|---|---|---|---|
| 1 | 성능·평가/04_미검증_항목_대장 §2-⑭ | server-team | 수정 | 항목을 해소로 표기 | server#101 |
| 2 | 아키텍처/03_AI_gRPC_계약과_와이어포맷 | server-team | 추가 | 스트림 수명 계약 절 | client.go 실측 |

• 신규 문서가 있으면 "왜 병합이 아닌가"를 함께 적는다.
• 사용자는 항목을 골라 답한다. 선택되지 않은 항목은 진행하지 않는다.
• as_of·last_verified는 자동으로 오늘로 밀지 않는다. 판단 규칙은 Step 5에 있다.

verification 조정도 계획에 올린다

내용을 고치면 등급이 따라 움직이는 경우가 많다. Step 5에서 뒤늦게 판단하면 방향을 놓친다. 표에 별도 행으로 올리고 근거를 함께 적는다.

이번 변경이 무엇인가	등급
새 근거가 생겼다 — 코드 대조·실행 관측·정본 대조	올린다
미검증 내용을 보탰다 / 본문 일부가 낡았음이 드러났다	내린다 — partial
둘 다 아니다 — 오타·링크·표기	그대로

CRITICAL: "근거가 늘었으니 올린다"로 반사적으로 가지 않는다. 실측이 드러낸 것이 "규정과 실무가 어긋난다" 거나 "일부가 낡았다" 라면 그건 내리는 근거다. 새 사실을 보탰다는 것과 문서가 더 믿을 만해졌다는 것은 다르다.

등급이 partial 이하로 내려가면 "정본처럼 인용하지 않는다" 는 규율이 걸린다. 규범을 담은 문서라면 그 부작용까지 함께 보고하고 사용자가 정하게 한다. 조정 기준은 references/wiki-conventions.md.

owner가 다른 팀인 문서는 표에서 짚고 따로 확인받는다. 정본 책임이 그 팀에 있다는 뜻이고, 문서명만 보면 누구 소관인지 드러나지 않는다.

"3번은 owner: ai-team 문서입니다. 사실이 틀렸거나 낡은 건 고쳐도 되지만, 해석이나 판단을 바꾸는 수정이면 AI 담당 확인이 필요합니다. 어떻게 할까요?"

오타·깨진 링크·표기 통일처럼 소유권과 무관한 수정은 그냥 진행한다. 판단·해석·결론을 바꾸는 수정만 이 확인이 필요하다.

삭제 항목이 있으면 Step 5 직전에 한 번 더 확인한다. 참조 수를 세어 함께 보여준다.

grep -rn "\[\[문서명\]\]" "$WIKI" | wc -l

"규약/07을 지웁니다. 참조가 6군데 있어 함께 정리해야 합니다. 진행할까요?"

Step 5: 수정

CRITICAL: 이 단계부터 파일이 바뀐다. 중간에 실패하거나 사용자가 항목을 철회하면 아래 롤백을 먼저 수행한 뒤 다음 행동을 정한다.

상황	롤백
사용자가 일부 항목을 철회	그 파일만 git -C "$WIKI" restore --staged --worktree 파일경로
Step 6 검사에서 되돌려야 함	위와 동일
전면 중단	Step 0의 "버리고 새로 시작" 절차를 그대로 따른다. 명령과 순서를 여기 옮겨 적지 않는다 — 갱신 지점이 둘이 되면 어긋난다
커밋까지 했는데 중단	커밋은 남긴다. 되돌리지 않고 브랜치 상태를 보고한다 — 되돌리기는 사용자 판단이다

승인된 항목만 Read/Edit/Write로 고친다.

• as_of·last_verified는 실제로 확인한 범위만큼만 손댄다 — 아래 "날짜 필드"
• verification은 근거 수준에 맞게. 올리는 것뿐 아니라 내리는 것도 한다 — 등급표와 조정 기준은 references/wiki-conventions.md
• 문체는 주변 문서를 모방한다
• 변동 수치는 _현행_수치.md에만 두고 다른 문서는 링크만 건다

날짜 필드를 함부로 밀지 않는다

한 절만 고쳐놓고 last_verified를 오늘로 바꾸면 문서 전체가 오늘 검증된 것처럼 보인다. 나머지 절이 반년 전 것이어도 그렇다. 정본은 이 값을 노후 판단에 쓰라고 명시한다 — "오래된 관측이면 현재 상태와 다를 수 있다." 매번 리셋하면 위키 전체가 그 신호를 잃는다.

무엇을 했나	last_verified
문서 전체를 현행 근거로 다시 대조했다	오늘로
일부 절만 고쳤다	그대로 둔다. 근거와 시점은 고친 절의 본문에 적는다
오타·링크·표기만 고쳤다	그대로 둔다

as_of는 본문이 서술하는 상태의 기준 시점이다. 새로 관측하거나 대조한 사실을 넣었을 때만 옮긴다.

⚠️ 두 필드의 차이는 정본에도 정의돼 있지 않다. 현행 148문서는 둘이 100% 같은 값이다. 위 표는 정본 §6의 취지에서 끌어낸 잠정 운용이며, 팀이 정의를 확정하면 그쪽을 따른다.

신규 문서를 만들었다면 세 가지가 반드시 따라온다. 하나라도 빠지면 문서가 어디서도 도달되지 않거나 색인이 실제와 어긋난다.

1. 3층 색인에 링크 추가 — 지식베이스/_00_서버_지식베이스.md(서버) / _01_클라이언트_지식베이스.md(C 접두) / _02_AI_지식베이스.md(A 접두). 해당 갈래 목록에 한 줄
2. 2층 허브에 링크 추가 — 서버.md / 클라이언트.md / AI.md
3. 문서 수 카운트 갱신 — 색인의 갈래별 수, 허브의 갈래 제목, innolive.md의 총계

카운트는 실제 파일 수와 대조한다.

ls "$WIKI/지식베이스/<갈래>/" | grep -v '^[AC][0-9]' | wc -l   # 서버 문서 수

상세 규칙은 references/wiki-conventions.md의 "문서를 새로 만들 때" 절에 있다.

Step 6: 오염 자체검사

CRITICAL: 커밋 전에 아래를 전부 확인한다. 하나라도 걸리면 고치고 다시 검사한다.

검사	걸리는 예	고치는 법
개인 규칙	"담당자의 명시적 위임이 있을 때만", "제지됐다", "게이트가 열렸다"	삭제. 판단 기준은 Step 2의 "개인 합의" — 여기는 그때 놓친 것을 잡는 자리다
개인 경로	~/Documents/..., 개인 vault, 개인 사이드 프로젝트명	삭제하거나 일반화
주체 불명	"사용자가 지적했다" (팀원을 가리킬 때)	역할로 — "서버 담당", "AI 담당", "클라이언트 담당"
[당시] 누락	과거 상태를 현재형으로 서술	[당시] 추가
수치 복제	배포 태그·MAX_SESSIONS를 다른 문서에 적음	_현행_수치 링크로 교체
레포 미명시	"#100"	server#100 / client#100 / ai#100
사적 정보	개인 이메일, 자격증명 값, SHA-1 지문	존재만 표기, 값은 옮기지 않는다

"사용자"는 제품 사용자를 가리킬 때만 쓴다. 팀원을 뜻한다면 전부 역할로 바꾼다.

링크와 frontmatter도 확인한다.

• [[...]] 링크가 실재하는 문서를 가리키는가
• frontmatter가 domain → question → owner → verification 순인가

Step 7: 브랜치·커밋·PR

gh api user --jq .login          # GitHub ID

git config user.name은 쓰지 않는다. 팀에 한글 실명을 쓰는 사람이 있어 브랜치명이 깨진다. gh 인증이 안 돼 있으면 사용자에게 ID를 직접 묻는다.

git -C "$WIKI" switch -c "GITHUB_ID/작업명"
git -C "$WIKI" add 바꾼-파일만
git -C "$WIKI" commit -m "커밋 메시지"

• 브랜치명: GITHUB_ID/작업명. 작업명은 영문 kebab-case — 한글은 일부 CI·터미널에서 깨진다
• 커밋 메시지: 에이전트가 작성한다. 한국어로 쓰고 1커밋으로 만든다
• 브랜치가 이미 있으면 알리고 확인받는다. 덮지 않는다

push 전에 멈춘다 (두 번째 승인 게이트)

CRITICAL: 여기가 원격에 나가는 첫 지점이다. Step 4에서 받은 승인은 "무엇을 고칠지" 였고, 여기서 받는 승인은 "이대로 팀 레포에 올릴지" 다. 둘은 다르다 — 계획과 실제 커밋이 어긋났을 수도, 작업 자체가 레포에 올릴 성격이 아니었을 수도 있다.

git -C "$WIKI" log --oneline -1        # 커밋 메시지
git -C "$WIKI" show --stat HEAD        # 실제로 바뀐 것
git -C "$WIKI" branch --show-current   # 브랜치명

세 출력을 보여주고 묻는다.

"GITHUB_ID/작업명 브랜치에 커밋했습니다. push하고 PR을 열까요?"

여기서 멈추는 것도 정상 종료다. 커밋은 로컬에 남고 원격에는 아무것도 안 나간다. 그만두기로 하면 브랜치를 어떻게 할지 묻고 끝낸다 — 임의로 지우지 않는다.

승인받으면 push한다.

git -C "$WIKI" push -u origin "GITHUB_ID/작업명"

PR 직전에 관련 이슈를 묻는다:

"관련된 서버/클라/AI 레포 이슈나 PR이 있나요? PR 본문에 링크로 남기겠습니다."

없으면 그냥 진행한다. 위키 변경에 이슈는 필수가 아니다.

gh pr create --repo team-framework/framework-llm-wiki \
  --title "커밋 메시지와 동일" \
  --body "관련: team-framework/innolive-server#100

- 문서: 바꾼 내용
- 문서: 바꾼 내용"

관련 이슈는 team-framework/innolive-server#100 처럼 풀 경로로 적는다. #100만 쓰면 위키 레포의 이슈로 오인된다.

Step 8: 보고

PR URL을 보고하고 멈춘다.

"머지 후 홈서버 동기화·재색인이 끝나야 search_wiki에 반영됩니다. 반영 여부는 get_wiki_status로 확인할 수 있습니다."

Examples

Example 1: 기존 문서 보강

사용자: "위키 업데이트해줘" — 경쟁 상태 수정 PR을 막 머지한 뒤

1. 경로를 묻고 검증 3종 통과
2. pull --ff-only → get_wiki_status로 색인 대조
3. 인입 판정 — 수정 사실은 사실, "다세션에서도 안 나올 것"은 가설로 분리
4. search_wiki(query="ai client 경쟁 상태 goroutine") → 04_미검증_항목_대장이 score 10으로 상위. question을 보니 이미 다루는 주제 → 신규 문서 만들지 않음
5. 계획 제시 → 사용자가 "1번은 지우지 말고 해소됐다고만 적어"
6. 삭제 → 수정으로 바꿔 반영
7. 자체검사에서 "사용자가 지적한 대로"를 발견 → "서버 담당이"로 교정
8. itzjb/ai-client-race-fix 브랜치로 PR

Example 2: 위키에 넣지 않는 경우

사용자: "이 버그 위키에 남겨줘" — 재현은 안 해본 상태

• 인입 판정에서 가설로 분류
• 계획에 "미확인 항목으로 04_미검증_항목_대장에 추가"로 올린다
• 사실처럼 서술하지 않는다

Troubleshooting

pull --ff-only 실패

원인: 로컬에 커밋되지 않은 변경이나 갈라진 커밋이 있다. 조치: 중단하고 사용자에게 알린다. reset --hard로 밀지 않는다 — 팀원의 작업일 수 있다.

rev-parse --git-dir 실패

원인: 클론이 아니라 파일 복사본이다. 조치: 중단한다. 커밋할 수 없다. 클론 경로를 다시 묻는다.

remote가 framework-llm-wiki가 아님

원인: 경로를 잘못 받았거나 동명의 다른 폴더다. 조치: 경로를 다시 묻는다.

get_wiki_status의 wiki_commit이 null

원인: MCP가 마운트한 위키가 git 클론이 아니거나 .git이 빠져 있다. 조치: 대조를 포기하고 로컬 pull 결과를 기준으로 진행한다. 그 사실을 사용자에게 한 줄로 알린다. MCP 담당자에게 전달할 사안이다.

search_wiki가 방금 머지한 내용을 못 찾음

원인: 재색인이 아직 안 끝났다. 조치: 정상이다. 로컬 파일을 근거로 판단하되 그 사실을 밝힌다.

Step 0에서 워킹트리가 더러움

원인: 이 스킬의 이전 실행이 Step 5 이후에 죽었거나, 팀원이 작업 중이다. 브랜치 이름으로는 구분되지 않는다 — GITHUB_ID/작업명은 팀 브랜치 규칙이라 양쪽이 같은 형태이고, Step 5~6에서 죽었으면 브랜치는 아직 main이다. 조치: Step 0의 "워킹트리가 더러울 때"를 따른다. 임의로 판정하지도 지우지도 않는다 — 성격 판정과 처리 모두 사용자가 정한다.

"버리고 새로 시작" 후에도 status가 비지 않음

원인: restore .가 추적되지 않는 파일(??)을 지우지 않는다. 신규 문서를 만들다 죽은 경우다. 조치: clean -nd로 지워질 목록을 보여주고 확인받은 뒤 clean -fd. 그래도 남으면 .gitignore 대상일 수 있으니 진행하지 말고 보고한다.

push 실패

원인: 권한 없음, 네트워크, 또는 protected branch 규칙. 조치: 커밋은 그대로 둔다. 브랜치명과 커밋 SHA를 보고하고 사용자에게 넘긴다. 되돌리지 않는다 — 작업이 사라진다.

gh pr create 실패

원인: gh 권한, 이미 같은 브랜치의 PR이 열려 있음, 또는 레포 설정. 조치: 커밋과 push는 이미 성공한 상태다. 브랜치명을 보고하고, 사용자가 웹에서 PR을 만들 수 있게 안내한다.

gh 인증 실패

원인: gh auth login이 안 돼 있다. 조치: 사용자에게 GitHub ID를 직접 묻는다.

브랜치가 이미 존재

원인: 같은 작업을 다시 돌렸거나 이전 시도가 남아 있다. 조치: 알리고 확인받는다. 이어 쓸지 새 이름으로 갈지는 사용자가 정한다.

References

• references/wiki-conventions.md — frontmatter 4필드, verification 등급, 층 구조, 도메인 접두, 표기 규율