@simplysm/sd-claude 14.0.55 → 14.0.57

package/claude/skills/sd-debug/SKILL.md

@@ -1,56 +1,347 @@
 ---
 name: sd-debug
-description: 버그·동작 이상의 근본 원인 분석 및 해결책을 제안하는 스킬. "디버그", "에러 분석", "버그 원인 찾아줘", "왜 이렇게 동작해?" 등을 요청할 때 사용한다.
+description: 버그·동작 이상의 근본 원인을 RCA(Root Cause Analysis) 기법과 ACH(Analysis of Competing Hypotheses)로 분석하여 보고하는 스킬. "디버그", "에러 분석", "버그 원인 찾아줘", "왜 이렇게 동작해?", "왜 안 돼?" 등을 요청할 때 사용한다. 분석과 보고만 수행하고 코드 수정·후속 스킬 호출은 하지 않는다. 단순 코드 리뷰는 sd-review를, 기능 추가/수정은 sd-dev를 사용한다.
 ---
 
-# sd-debug: 근본 원인 분석
+# sd-debug: 근본 원인 분석 및 보고
 
-## Step 1: 근본 원인 분석
+버그·동작 이상을 RCA 기법(Fishbone → 5 Whys → FTA)과 ACH 매트릭스로 분석하여 근본 원인과 해결책을 보고한 뒤 즉시 종료한다.
 
-`/sd-inner-debug` 스킬을 호출한다.
+분석 파이프라인:
 
-**CRITICAL: 이 단계에서는 분석과 방안 선택만 수행한다. 코드 수정은 절대(NEVER) 하지 않는다.** 코드 수정은 Step 3에서 `/sd-dev`를 통해서만 수행한다.
+```
+Phase 0: 진입 가드
+   ↓
+Phase 1: 증거 수집
+   ↓
+Phase 2: 재현 & 최소화          [Delta Debugging]
+   ↓
+Phase 3: Fishbone 분기          [RCA — 가설 발산, ≥3개]
+   ↓
+Phase 4: ACH 매트릭스           [가설 × 증거 평가, 수렴]
+   ↓
+Phase 5: 분기형 5 Whys          [RCA — 인과 종축 추적]
+   ↓
+Phase 6: Fault Tree (조건부)    [RCA — 복합 인과]
+   ↓
+Phase 7: 보고 & 종료
+```
+
+## 분석 원칙
+
+- **근본 원인 제거**: 증상을 숨기는 해결이 아닌, 원인 자체를 제거하는 방향으로 분석한다. 반드시 "왜 이 문제가 발생하는가?"를 근원까지 추적한다.
+- **추측 금지**: "~일 수 있다", "~가능성이 높다"로 원인을 단정하지 않는다. 코드를 읽고, 로그를 확인하고, 재현하여 증거 기반으로 원인을 특정한다.
+- **외부 탓 금지**: 라이브러리/런타임 버그를 원인으로 지목하기 전에, 내 코드가 해당 API를 올바르게 사용하고 있는지 먼저 검증한다. 공식 문서·소스코드·이슈 트래커에서 동일 보고가 없으면 내 코드 문제로 간주한다.
+- **반증 우선 (Falsification First)**: 가설을 입증하려 하지 말고, 매 단계 "어떻게 하면 이 가설이 *틀릴 수 있는가*"를 먼저 묻는다.
+- **One variable at a time**: 검증 시 한 번에 한 변수만 변경한다. 동시 변경은 인과 식별을 깬다.
+- **분석·보고에서 종료**: 분석과 보고만 수행한다. 코드 수정이나 후속 스킬 호출을 하지 않는다. 후속 작업은 사용자 지시를 받은 뒤에만 시작한다.
+
+### 편법/우회방법 금지 목록
+
+해결책으로 다음을 제안하는 것을 금지한다.
+
+| 편법(예시)                                   | 문제                                                       |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| `setTimeout` / `requestAnimationFrame`       | 타이밍 문제를 회피할 뿐 해결하지 않는다                    |
+| `try-catch`로 에러 무시                      | 런타임 문제를 숨긴다                                       |
+| `as any` / `any` 타입                        | 타입 안전성을 포기한다                                     |
+| `@ts-ignore` / `@ts-expect-error`            | 타입 에러를 숨길 뿐 해결하지 않는다                        |
+| `// eslint-disable` / `/* eslint-disable */` | 린트 규칙을 무력화한다                                     |
+| 플래그 변수 (`isReady`, `isLoaded`)          | 조건을 우회한다                                            |
+| `?.` 옵셔널 체이닝으로 undefined 무시        | 값이 undefined/null인 원인을 추적하지 않고 `?.`로 무시한다 |
+| `.skip` / 테스트 삭제                        | 테스트 커버리지를 줄인다                                   |
+
+### 증거 등급
+
+증거를 가설에 매핑할 때 다음 등급으로 표기한다.
+
+- **C(code)**: 코드에서 직접 관찰 (변수값, 호출 체인, 설정 파일, 타입 정의 등)
+- **C(doc)**: 공식 문서, GitHub 이슈, changelog, 라이브러리 소스 코드에서 확인
+- **C(infer)**: 직접 확인 불가, 추론에 기반 — 이 등급만으로는 가설을 확정할 수 없다
+- **I**: 증거가 가설과 불일치 — 코드에서 직접 관찰 가능한 모순이 있을 때만 표시. 추론에 의한 I 표시 금지
+- **N**: 증거가 가설과 무관
+
+외부 라이브러리/프레임워크 동작에 대한 가설(예: "X 라이브러리가 Y를 인식하지 못한다")은 반드시 다음 중 하나로 뒷받침해야 `C(doc)` 이상이 된다.
+
+- GitHub 이슈 (`gh search issues` 또는 `WebSearch`로 검색)
+- 공식 문서/changelog
+- 라이브러리 소스 코드에서 해당 동작을 직접 확인
+
+뒷받침 없이 "그럴 것이다"라고 추정하면 `C(infer)`이며, 이것만으로는 가설을 확정할 수 없다.
+
+### 인지편향 가드
+
+LLM 디버깅의 주요 실패 모드와 차단 룰.
+
+- **Anchor bias** — 첫 가설에 매달리는 편향: Phase 3에서 가설 ≥3개 강제로 차단
+- **Confirmation bias** — 가설 부합 증거만 수집하는 편향: Phase 4의 가설 × 증거 매트릭스로 모든 증거를 모든 가설에 평가하여 차단
+- **단일 인과사슬 함정** — "왜?"가 한 줄로 좁아지는 편향: Phase 5에서 매 단계 ≥2 분기 강제로 차단
+- **Falsification 누락** — 가설 입증만 하는 편향: 모든 검증 실험 전에 "이 가설을 어떻게 깨뜨릴 수 있는가" 먼저 명시
+
+## Phase 0: 진입 가드
+
+입력에서 의도를 분리한다.
+
+- "디버그", "왜 이래?", "원인 찾아줘", "에러 분석" → 분석 모드
+- "고쳐줘", "수정해줘", "바꿔줘" → 분석 모드 + 후속 수정 핸드오프 의사. 단, 본 스킬은 분석/보고에서 종료하며, 수정은 사용자가 별도 지시 후 `/sd-dev` 등을 호출해야 한다.
+
+분석 모드에서는 어떤 코드 수정도 하지 않는다. 진단용 print/assert 삽입도 직접 수행하지 않으며, 필요시 Phase 4의 검증 실험으로만 *지시* 한다.
+
+## Phase 1: 증거 수집
+
+### 1-1. GitHub 이슈 입력
+
+입력이 GitHub 이슈 참조(`owner/repo#N` 또는 `#N`)인 경우, `gh issue view`로 이슈 내용을 조회하여 아래 항목을 추출한다. `#N`만 입력된 경우 현재 리포의 이슈로 간주한다.
+
+### 1-2. 추출 항목
+
+사용자 입력(또는 조회된 이슈)에서 다음을 추출한다.
+
+- **증상** — 해당하는 유형으로 기록
+  - 에러 유형: 에러 메시지 원문 인용
+  - 동작 이상 유형: 기대 동작과 실제 동작을 각각 명시
+- **위치** — 에러 발생 `파일:라인` 또는 관련 기능/화면
+- **재현 절차** — 문제가 발생하는 구체적 조작 순서
+- **환경** — OS, 런타임 버전, 입력 데이터, 시점 (간헐 발생 여부)
+- **최근 변경** — 언제부터 발생했는지, 관련 커밋
+- **출처** — GitHub 이슈에서 시작된 경우 `owner/repo#N` 형식. 그 외에는 `direct`
+
+누락 항목이 있으면 `/sd-inner-clarify` 스킬을 호출하여 명확화한다.
+
+## Phase 2: 재현 & 최소화
+
+### 2-1. 재현 가능성 분류
+
+먼저 이 버그가 LLM 환경에서 직접 재현 가능한지 분류한다. 분류 결과에 따라 2-2~2-4 중 적용 분기가 결정된다.
+
+| 레벨 | 정의                       | 예시                                                          |
+| ---- | -------------------------- | ------------------------------------------------------------- |
+| L1   | LLM 직접 재현 가능         | 단위·통합 테스트 실패, dev 서버 실행 시 에러, 코드/입력만으로 재현 |
+| L2   | 사용자 환경 의존           | 특정 OS/브라우저 버전, 사용자 설정·데이터, 특정 시점          |
+| L3   | 하드웨어 의존              | 디바이스, USB/시리얼/카메라/GPS, Capacitor 플러그인           |
+| L4   | 간헐 발생                  | race condition, 메모리 압력, 타이밍                           |
+| L5   | 프로덕션 데이터 의존       | 실제 DB 상태, 외부 API 응답 시점, 사용자별 데이터             |
+
+분류가 모호하면 사용자에게 단일 질문으로 확인한다. 한 버그가 복수 레벨에 해당할 수 있다 (예: L3 + L4).
+
+### 2-2. L1 처리 — 직접 재현 + Delta Debugging
+
+L1 케이스에서는 수집된 재현 절차를 도구로 직접 실행하여 증상을 재현한다. 재현하지 않고 가설 단계로 넘어가는 것은 금지한다.
+
+- 코드 실행 (`pnpm test`, `pnpm dev` 등)
+- 입력 데이터 주입
+- 환경/설정 적용
+
+재현 성공 시 Delta Debugging 알고리즘으로 1-minimal 케이스까지 축소한다.
+
+1. 실패하는 입력/변경 집합 D를 절반으로 분할 (D1, D2)
+2. D1, D2 각각으로 테스트
+   - 한쪽에서 실패 재현되면 그쪽으로 좁히기
+   - 양쪽 모두 실패 안 하면 더 작게 쪼개기
+3. 한 글자/한 줄도 빼지 못하는 minimal까지 반복
+
+적용 대상:
+
+- 입력 데이터 — 어떤 레코드가 깨뜨리는가
+- 코드 변경 — `git bisect`로 어떤 커밋이 도입했는가
+- 파일/함수 — 어떤 호출이 원인인가
+
+상세 알고리즘은 `references/repro-minimize.md` 참조.
+
+### 2-3. L2~L5 처리 — 사용자 협업 정보 수집
+
+LLM이 직접 재현할 수 없는 케이스에서는 사용자에게 정보 수집을 요청한다. 레벨별 필수 수집 항목:
+
+| 레벨 | 수집 항목                                                                                          |
+| ---- | -------------------------------------------------------------------------------------------------- |
+| L2   | 정확한 재현 절차, 콘솔 로그, 네트워크 캡처 (HAR), 스크린샷/영상, 환경 정보 (OS·브라우저·버전·로케일) |
+| L3   | 디바이스 로그 (`adb logcat` / Xcode console / 시리얼 dump), 디바이스 모델·OS 버전, 주변기기 사양·연결 상태 |
+| L4   | 재현 빈도 (N/M회), 발생 시점 패턴, 발생 직전 상태·조작, 동시성 조건 (동시 사용자 수, 부하)         |
+| L5   | 익명화된 요청/응답 페이로드, DB 스키마 + 샘플 row, 발생 시점의 외부 API 응답·시각                  |
+
+요청은 단일 질문으로 묶어 사용자 부담을 줄인다. 수집된 정보를 Phase 4의 ACH 매트릭스 증거로 등록한다. 상세는 `references/repro-collab.md` 참조.
+
+### 2-4. 재현 불가 모드의 가설 검증
+
+L2~L5에서 사용자 정보를 받아도 LLM이 직접 실행으로 검증할 수 없는 부분이 남는다. 이 모드에서는:
+
+- **트레이스 시뮬레이션**: 코드 트레이스·로직 분석·타입 체크로 가설을 좁힌다 (실행 없이)
+- **C(infer) 인정**: Phase 4 ACH 매트릭스에서 C(infer) 비중이 자연스럽게 높아짐. 매트릭스 갱신 단계마다 *추가 사용자 데이터 요청* 을 트리거하여 C(infer)를 C(code)/C(doc)으로 승격시키도록 노력한다
+- **단정 금지**: 단정적 결론을 피하고, 살아남은 가설이 복수면 모두 보고한다
+- **재현 한계 명시**: Phase 7 보고에서 "직접 재현 못 한 부분"을 분석 한계 섹션에 분리해 적는다
 
-## Step 2: 문서 기록
+## Phase 3: Fishbone 분기 — 가설 발산
 
-Step 1의 분석과 선택 결과를 문서에 기록한다. **코드 수정 전에 반드시 이 단계를 먼저 완료한다.**
+### 3-1. 6축 카테고리
 
-### 출력 경로
+수집된 증거로부터 다음 6축에 대해 각각 가설을 1개 이상 생성한다. 전체 가설 수는 **3개 이상**이어야 한다.
 
-산출물 경로: `.tasks/{yyMMddHHmmss}_debug-{topic}/debug.md`
+| 축              | 예시 |
+|-----------------|------|
+| 코드            | 로직 오류, 타입 불일치, 순서/조건 오류 |
+| 입력·데이터     | 예상 못 한 값, NULL/빈 값, 인코딩, 경계값 |
+| 환경·설정       | 환경변수, 설정 파일, 의존성 버전, 빌드 타겟 |
+| 타이밍·동시성   | race condition, async 순서, 트랜잭션 격리 |
+| 외부 의존       | 라이브러리 버그/변경, API 응답 변경, DB 스키마 변경 |
+| 상태 관리       | 캐시/메모리 상태, 잘못된 초기화, 잔존 상태 |
 
-- `{yyMMddHHmmss}` — Bash `date +%y%m%d%H%M%S`로 취득. LLM이 생성한 타임스탬프 금지
-- `{topic}` — 에러/이슈의 핵심을 나타내는 간결한 키워드 (예: `null-ref`, `race-condition`, `async-init`)
+상세 가이드는 `references/fishbone-categories.md` 참조.
 
-### debug.md 형식
+### 3-2. 가설 형식
 
-```markdown
-# 디버그: {문제 한 줄 요약}
+각 가설은 다음 형식으로 명시한다.
 
-## 출처
+- **가설 ID**: H1, H2, ...
+- **카테고리**: 6축 중 하나
+- **주장**: "X가 Y이다" 또는 "X가 Y하기 때문에 Z가 발생한다"
+- **검증 가능성**: 어떤 실험으로 입증/반증할 수 있는가
 
-- **origin:** `{출처}` — GitHub 이슈에서 시작된 경우 `owner/repo#N` 형식. 그 외에는 `direct` (사용자 직접 입력)
-- **완료 시 참고:** GitHub 이슈인 경우, 수정 완료 후 해당 이슈의 close 및 comment가 필요할 수 있다.
+가설은 사용자에게 출력하지 않고 내부 작업으로 유지한다 (Phase 7 보고에서는 살아남은 원인만 노출).
 
-## 문제 증상
+## Phase 4: ACH 매트릭스 — 가설 평가
 
-- **유형:** 에러 / 동작 이상
-- **증상:** `{에러 메시지 원문}` 또는 기대: {기대 동작} / 실제: {실제 동작}
-- **위치:** `{file_path:line_number}` 또는 {관련 기능/화면}
-- **재현 절차:** {조작 순서}
+### 4-1. 매트릭스 초기화
 
-## 근본 원인
+가설(열) × 증거(행) 매트릭스를 구성한다. 현재까지 수집된 증거(에러 메시지, 재현 조건, 코드 분석 결과)를 초기 증거로 등록한다.
 
-{ACH 분석으로 확정된 원인 설명}
+```
+              | H1       | H2       | H3       | ...
+--------------|----------|----------|----------|
+증거 E1       | C(code)  | I        | N        |
+증거 E2       | I        | C(doc)   | C(infer) |
+증거 E3       | C(code)  | C(code)  | I        |
+```
+
+### 4-2. 판별 실험 → 매트릭스 갱신
+
+가설을 가장 많이 구분할 수 있는 검증 도구를 선택하여 실험한다.
+
+| 검증 도구          | 적용 조건                                          |
+| ------------------ | -------------------------------------------------- |
+| 역추적             | 스택 트레이스가 있거나 문제 발현 지점이 명확할 때  |
+| 데이터 흐름 추적   | 잘못된 값이 출력되거나 기대와 다른 결과가 나올 때  |
+| 변경 이력 분석     | "이전엔 됐는데 안 됨", 회귀가 의심될 때            |
+| 제약 조건 추론     | 간헐적이거나 특정 환경/입력에서만 발생할 때        |
+
+상세 적용법은 `references/verification-tools.md` 참조.
+
+각 실험마다 "이 실험으로 어떤 가설이 *반증* 될 수 있는가"를 먼저 명시한다 (Falsification First). 실험 결과를 새 증거로 매트릭스에 추가하고, 각 가설에 대해 C(code)/C(doc)/C(infer)/I/N을 표시한다.
+
+### 4-3. 가설 폐기 룰
+
+- **I(불일치)** 표시가 있는 가설은 폐기한다 (코드에서 직접 관찰 가능한 모순일 때만)
+- **C(infer)만으로 구성된 가설**은 확정 불가 — 추가 증거 필요 (다음 실험 대상)
+- **C(code) 또는 C(doc)으로 충분히 뒷받침되고 I가 없는 가설**이 살아남은 가설
+
+### 4-4. 분석 한계 명시
+
+런타임 데이터(API 응답, DB 결과 등)를 직접 확인할 수 없는 경우, 그 한계를 ACH 결과에 명시한다 — "실제 데이터를 확인하지 못했으므로 추정에 기반한 판정"임을 밝힌다.
+
+### 4-5. 반복 종료 조건
 
-## 해결 방안
+- 살아남은 가설이 1개로 좁혀지면 Phase 5로 진행
+- 살아남은 가설이 복수면 Phase 5에서 각각 종축 추적
+- 살아남은 가설이 0개면 Phase 1로 돌아가 추가 증거 수집 또는 사용자에게 추가 컨텍스트 요청
+
+상세 매트릭스 작성 가이드는 `references/ach-matrix.md` 참조.
+
+## Phase 5: 분기형 5 Whys — 인과 종축 추적
+
+### 5-1. 적용 대상
+
+Phase 4에서 살아남은 각 가설에 대해 "왜?"를 반복하여 표면 원인 → 근본 원인까지 추적한다.
+
+### 5-2. 분기 강제
+
+매 "왜?" 단계마다 **2개 이상의 분기 후보**를 나열하고, 그중 증거로 뒷받침되는 분기만 채택한다. 단일 인과사슬에 갇히지 않는다.
 
-- **방안:** {선택된 방안 이름}
-- **설명:** {구현 방향, 코드 예시 포함}
-- **선택 사유:** {사용자 코멘트 또는 선택 근거}
 ```
+증상: null row가 결과에 섞임
+└ 왜? 트랜잭션 격리 위반
+   ├ 왜? 풀 재사용 시 prepared statement 캐시 공유   ← C(code) 채택
+   │  └ 왜? cache key에 connection id 누락           ← ROOT
+   └ 왜? isolation level 잘못 설정                    ← I 폐기
+```
+
+### 5-3. 종료 조건
+
+- 더 이상 "왜?"를 물을 수 없는 지점 = ROOT
+- 또는 코드/설정/외부 의존의 *수정 가능한 지점* 에 도달
+
+상세 템플릿은 `references/branching-5whys.md` 참조.
+
+## Phase 6: Fault Tree Analysis (조건부)
+
+### 6-1. 적용 조건
+
+Phase 5에서 단일 ROOT가 아니라 **두 개 이상의 원인이 결합** 되어야 발생하는 경우만 적용한다.
+
+- AND 결합: 모든 조건이 동시에 만족되어야 발생
+- OR 결합: 어느 하나라도 만족되면 발생
+
+### 6-2. 트리 구조
+
+```
+        [증상]
+          |
+        [AND]
+        /   \
+   [원인1]  [원인2]
+      |       |
+    [OR]    [...]
+   /    \
+ [a]    [b]
+```
+
+단일 원인 케이스에서는 Phase 6을 생략한다.
+
+상세는 `references/fta-template.md` 참조.
+
+## Phase 7: 보고 & 종료
+
+분석 결과를 아래 양식대로 한 번의 응답으로 출력하고 즉시 종료한다. 사용자가 다음 메시지로 후속 작업을 지시하기 전까지 추가 행동을 하지 않는다.
+
+### 출력 원칙
+
+- **결론 우선**: 첫 줄에 확정된 원인을 한 문장으로 결론짓는다.
+- **분석 메타정보 비출력**: ACH 매트릭스, 5 Whys 트리 전체, 폐기된 가설, 검증 도구 사용 과정은 보고에 포함하지 않는다. 살아남은 원인과 그 근거만 간결하게 노출한다.
+- **근거는 인용으로**: 원인을 뒷받침하는 코드는 `파일경로:라인` 인용 + 코드블록으로 제시한다. 사용자가 원본 파일을 열지 않아도 판단 가능해야 한다.
+- **해결책은 구체적으로**: 어디를(파일·라인·심볼), 어떻게(현재 → 변경 또는 시그니처) 바꿀지 명시한다. 구체화 불가하면 그 이유와 추가로 필요한 정보를 적는다.
+- **반론·위험 명시**: 권장 해결책에도 부작용·놓친 시나리오·반론이 있으면 함께 적는다.
+- **분석 한계 명시**: 런타임 데이터 미확인, 재현 한계, 추정 기반 부분이 있으면 분리해서 적는다.
+- **편법 사용 금지**: 해결책에 위 "편법/우회방법 금지 목록"의 항목을 사용하지 않는다.
+
+### 보고 양식
+
+```
+## 원인
+{확정 원인 1줄 결론}
+
+### 근거
+- {파일:라인 인용 + 관찰 사실}
+- (필요 시 코드블록으로 인용)
+
+### 분석 한계
+- {직접 확인 못 한 런타임 데이터 / 재현 한계 / 추정 기반 부분}
+
+## 해결책
+
+### 권장: {방안명}
+- 위치: {파일:라인 또는 심볼}
+- 변경 방향: {현재 → 변경 (코드블록 권장)}
+- 근거: 왜 이게 근본 해결인가
+- 위험·반론: {부작용·놓친 시나리오}
+
+### 대안: {방안명} (필요 시)
+- (권장과 동일 형식)
+```
+
+원인이 복수로 살아남았다면 `## 원인` 아래에 원인1·원인2를 나란히 배치하고, `## 해결책` 아래에 원인별 권장/대안을 둔다. 분석 한계가 없으면 `### 분석 한계` 섹션은 생략한다.
+
+### 종료
 
-## Step 3: 수정 개발
+보고 출력 후 즉시 종료한다. 사용자 지시 없이 다음을 하지 않는다.
 
-1. 대화에 출력파일(`debug.md`) 파일 경로를 표시한다.
-2. `/sd-dev` 스킬을 호출하여 수정 개발을 시작한다. **코드 수정은 반드시 이 단계에서 `/sd-dev`를 통해서만 수행한다.**
+- 코드 수정
+- 후속 스킬(`/sd-dev`, `/sd-tdd` 등) 자동 호출
+- 별도 파일 생성 (`debug.md` 등)

package/claude/skills/sd-debug/references/ach-matrix.md

@@ -0,0 +1,154 @@
+# ACH 매트릭스 — 가설 평가 가이드
+
+Phase 4에서 사용. 가설(열) × 증거(행) 매트릭스를 통해 가설을 객관적으로 수렴한다.
+
+ACH(Analysis of Competing Hypotheses)는 Richards Heuer Jr.(CIA, 1999)가 *인지편향(특히 confirmation bias)* 에 대응하기 위해 설계한 분석 프레임. LLM 디버깅의 가장 흔한 실패 모드인 "그럴듯한 가설 하나에 매달림"을 직접 차단한다.
+
+## 매트릭스 구조
+
+```
+              | H1       | H2       | H3       | ...
+--------------|----------|----------|----------|
+증거 E1       | C(code)  | I        | N        |
+증거 E2       | I        | C(doc)   | C(infer) |
+증거 E3       | C(code)  | C(code)  | I        |
+```
+
+- **행**: 증거 (관찰된 사실, 실험 결과, 사용자 보고, 코드 인용)
+- **열**: 가설 (Phase 3에서 발산된 H1~Hn)
+- **셀**: 해당 증거가 해당 가설과 어떻게 관계되는가
+
+## 셀 등급
+
+- **C(code)**: 코드에서 직접 관찰 — 변수값, 호출 체인, 설정 파일, 타입 정의
+- **C(doc)**: 공식 문서, GitHub 이슈, changelog, 라이브러리 소스 코드에서 확인
+- **C(infer)**: 직접 확인 불가, 추론에 기반 — *이 등급만으로는 가설을 확정할 수 없다*
+- **I**: 증거가 가설과 불일치 — 코드/문서에서 직접 관찰 가능한 모순일 때만 표시. 추론에 의한 I 표시 금지
+- **N**: 증거가 가설과 무관
+
+## 셀 등급 결정 트리
+
+```
+이 증거는 코드/문서/실행 결과에서 직접 관찰됐는가?
+├ Yes → 가설과 일치하는가?
+│       ├ Yes → 코드에서 직접? → C(code)
+│       │       문서/이슈에서? → C(doc)
+│       └ No  → 모순이 명확한가? → I
+│               (모순이 추론에 기반하면 → N, I 표기 금지)
+└ No  → 이 증거는 가설을 뒷받침/반증하는가?
+        ├ 추론으로 뒷받침 → C(infer)
+        └ 무관 → N
+```
+
+## 가설 폐기 룰
+
+다음에 해당하면 가설 폐기.
+
+- 한 행이라도 `I`(불일치)가 있고, 그 I가 *코드/문서에서 직접 관찰된 모순* 일 때
+- 추론에 의한 I 표시는 폐기 근거로 사용 금지
+
+폐기된 가설은 매트릭스에서 즉시 제거하지 않고 *표시만 변경* (취소선 또는 별도 섹션). 폐기 사유를 기록.
+
+## 외부 의존 가설의 특별 룰
+
+외부 라이브러리/프레임워크 동작에 대한 가설은 다음 중 하나로 뒷받침해야 `C(doc)` 이상이 된다.
+
+- GitHub 이슈 (`gh search issues` 또는 `WebSearch`로 검색)
+- 공식 문서/changelog
+- 라이브러리 소스 코드에서 해당 동작을 직접 확인
+
+뒷받침 없이 "그럴 것이다"라고 추정하면 `C(infer)`이며, 이것만으로는 가설을 확정할 수 없다.
+
+## 갱신 흐름
+
+```
+1. 현재 매트릭스 확인 → 어느 가설이 가장 모호한가
+2. 모호한 가설을 가장 잘 구분할 *판별 실험* 선택
+   (검증 도구 4종에서 선택, references/verification-tools.md)
+3. 실험 전에 "이 실험으로 어떤 가설이 *반증* 될 수 있는가" 명시 (Falsification First)
+4. 실험 수행 → 결과를 새 증거 E_new로 등록
+5. 모든 가설 열에 대해 E_new와의 관계 평가하여 셀 채움
+6. 폐기 룰 적용 → 가설 폐기
+7. 살아남은 가설 수 확인:
+   - 1개 → Phase 5 진입
+   - 복수 → 추가 실험 (2번으로 돌아감)
+   - 0개 → Phase 1로 돌아가 추가 컨텍스트 요청
+```
+
+## 가설 추가 절차
+
+분석 중 새 가설이 떠오르면:
+
+1. 새 가설 H_new를 열로 추가
+2. 기존 모든 증거(E1~En)에 대해 H_new와의 관계를 평가하여 셀 채움
+3. 새 가설이 추가됐다고 기존 가설을 자동 폐기하지 않음
+
+## C(infer) 승격 절차
+
+L2~L5 (재현 불가) 케이스에서 C(infer)가 다수일 때:
+
+1. C(infer) 셀이 가장 많은 가설을 식별
+2. 그 가설을 C(code)/C(doc)으로 승격할 수 있는 추가 데이터를 사용자에게 요청
+   (예: "디바이스 로그에서 X 메시지 확인되는지", "DB 샘플 row의 Y 컬럼 값")
+3. 받은 데이터로 셀 갱신
+4. 갱신 후 가설 분포 재평가
+
+## 사용자 출력 vs 내부 작업
+
+매트릭스는 **내부 작업**으로 유지. 사용자에게는 다음만 노출 (Phase 7 보고).
+
+- 살아남은 가설(원인) 결론
+- 그 가설을 뒷받침하는 증거
+
+매트릭스 자체, 폐기된 가설 목록, 셀 평가 과정은 보고에 포함하지 않는다.
+
+## 분석 한계 명시
+
+다음 경우 매트릭스에 한계를 함께 기록 → Phase 7 보고에 노출.
+
+- 런타임 데이터(API 응답, DB 결과)를 직접 확인 못 함
+- 재현 불가 (L2~L5 모드)
+- 외부 의존 가설을 C(doc)으로 검증 못 함
+- 복수 가설이 살아남았을 때
+
+## 인지편향 가드 (재명시)
+
+- **Confirmation bias 차단**: 매트릭스는 *모든 증거를 모든 가설에 대해 평가* 의무. 부합 증거만 모으는 것을 구조적으로 막는다.
+- **Anchor bias 차단**: 가설 ≥3 강제. 첫 가설로 직행 불가.
+- **Falsification 우선**: 실험 전에 "어떻게 깨뜨릴 수 있는가" 먼저. 입증 시도가 아닌 반증 시도.
+
+## 작은 매트릭스 예시 (전체 흐름)
+
+```
+초기 (Phase 3 가설 발산 후):
+
+              | H1 (정렬 비교) | H2 (입력 타입) | H3 (런타임 차이)
+--------------|----------------|----------------|------------------
+E1 (에러 메시지) | C(code)       | C(code)       | N
+E2 (재현 절차)  | C(code)       | C(code)       | C(infer)
+
+→ 모두 살아있음. 추가 실험 필요.
+
+E3 추가 (역추적 실험):
+
+E3 (호출 시점의 typeof 확인 → "number") | I            | N            | N
+
+→ H2 폐기 (입력은 number였음, string 가설 모순).
+
+E4 추가 (코드 트레이스 + MDN 확인):
+
+E4 (localeCompare는 모든 브라우저 동일 동작, MDN 확인) | N | -          | I
+
+→ H3 폐기.
+
+최종:
+
+              | H1 (정렬 비교) |
+--------------|----------------|
+E1            | C(code)       |
+E2            | C(code)       |
+E3            | -             |
+E4            | N             |
+
+→ 살아남은 가설 1개 (H1). Phase 5 진입.
+```

package/claude/skills/sd-debug/references/branching-5whys.md

@@ -0,0 +1,126 @@
+# 분기형 5 Whys — Phase 5 인과 종축 추적 가이드
+
+Phase 4에서 살아남은 가설(들)에 대해 표면 원인 → 근본 원인까지 인과 사슬을 따라간다. 표준 5 Whys (Toyota)의 *단일 사슬 함정* 을 분기 강제로 차단한다.
+
+## 분기 강제 룰
+
+매 "왜?" 단계마다 **분기 후보 ≥2개** 를 나열하고, 그중 증거로 뒷받침되는 분기만 채택한다. 단일 인과사슬에 갇히지 않는다.
+
+### 예시
+
+```
+증상: null row가 결과에 섞임
+└ 왜? 트랜잭션 격리 위반
+   ├ 왜? prepared statement 캐시 공유   ← C(code) → 채택
+   │  └ 왜? cache key에 connection id 누락   ← ROOT
+   ├ 왜? isolation level 잘못 설정      ← I → 폐기
+   └ 왜? 레플리카 복제 지연              ← C(infer) → 보류 (대안)
+```
+
+이 예시에서:
+
+- 첫 "왜?"의 답이 *바로 ROOT가 아닐 수 있음* — 더 깊이 파야 진짜 ROOT가 보인다
+- 분기 후보 3개 중 2개는 폐기/보류, 1개만 종축 진행
+- 보류된 대안은 채택된 분기가 ROOT가 아닐 경우의 백업
+
+## 종료 조건
+
+다음 중 하나에 도달하면 종료.
+
+- **수정 가능한 지점**: 코드/설정/외부 의존의 수정 가능한 위치
+- **외부 경계**: 외부 라이브러리/API/OS 동작 (수정 불가, 우회만 가능)
+- **물리적 제약**: 하드웨어 한계, 네트워크 지연 등 (수정 불가)
+
+종료 지점 = ROOT. ROOT가 외부 경계나 물리적 제약일 경우 *해결책은 우회 설계*가 된다 (편법/우회방법 금지표에 해당하는 것은 예외).
+
+## 분기 채택 룰
+
+각 "왜?" 분기는 ACH 등급으로 평가.
+
+| 등급         | 처리                                                    |
+| ------------ | ------------------------------------------------------- |
+| C(code)/C(doc) | 채택, 다음 "왜?"로 진행                                |
+| C(infer)       | 보류, 추가 증거 수집 또는 대안으로 기록                 |
+| I              | 폐기 (코드/문서에서 직접 관찰된 모순일 때만)            |
+| N              | 무관, 분기에서 제외                                     |
+
+C(infer)만으로 채택하지 않는다. 추가 증거로 C(code)/C(doc)으로 승격해야 채택.
+
+## 인지편향 가드
+
+### Anchor bias 차단
+
+- 첫 분기 후보에 매달리지 말 것
+- 매 단계 ≥2개 후보 나열 의무
+- 후보 1개만 떠오르면 의도적으로 다른 Fishbone 카테고리에서 후보 추가
+
+### Confirmation bias 차단
+
+- 채택한 분기를 *입증* 하려 하지 말고, 채택 후에도 다음 "왜?"에서 *반증 가능성* 을 먼저 묻기
+- "이 분기가 ROOT가 아닐 수 있는 시나리오는?"
+
+### Falsification 우선
+
+- 분기 채택 전에 "이 분기를 어떻게 깨뜨릴 수 있는가" 명시
+- 깨뜨릴 실험을 먼저 수행
+
+### 단일 인과사슬 함정 차단
+
+- 5 Whys가 한 줄로 좁아지면 위험 신호
+- 매 단계 분기 후보 수가 1개로 줄어들면 의도적으로 다른 카테고리에서 후보 추가
+- 표준 5 Whys의 가장 흔한 실패 모드
+
+## 트리 작성 형식
+
+```
+증상: <증상 1줄>
+└ 왜? <원인 1>                       ← <등급 또는 채택 여부>
+   ├ 왜? <원인 1-a>                  ← <등급>
+   │  └ 왜? <원인 1-a-i>             ← ROOT
+   └ 왜? <원인 1-b>                  ← <등급>
+└ 왜? <원인 2 (다른 분기)>           ← <등급>
+   └ ...
+```
+
+각 노드에 ACH 등급을 표기하여 채택/폐기 판단을 명시.
+
+## Phase 6 (FTA) 진입 조건
+
+5 Whys가 단일 ROOT가 아니라 **두 개 이상의 원인이 결합** 되어야 발생하는 형태로 끝나면 Phase 6으로 진입.
+
+예시:
+- ROOT-A AND ROOT-B 동시 만족 시 발생
+- ROOT-A OR ROOT-B 만족 시 발생
+
+단일 ROOT면 Phase 6 생략.
+
+## 깊이 vs 폭의 균형
+
+- 너무 얕음 (왜? 1~2회): 표면 원인에서 멈춤 → 증상 패치 위험
+- 너무 깊음 (왜? 7회 이상): 추상적 결론으로 흘러감 ("사람이 실수했기 때문" 등 비행동성 결론)
+- 적정: 3~5회 내에서 *수정 가능한 지점* 에 도달
+
+## 보고와의 분리
+
+5 Whys 트리 전체는 **내부 작업**. Phase 7 보고에는 ROOT만 결론으로 노출. 분기 후보, 폐기된 분기, 보류 대안은 보고에 포함하지 않는다 (단, 살아남은 ROOT가 복수면 모두 노출).
+
+## 5 Whys vs ACH 역할 분리
+
+- **ACH (Phase 4)**: *가설 횡축 평가* — 어느 가설이 살아남는가
+- **5 Whys (Phase 5)**: *인과 종축 추적* — 살아남은 가설의 진짜 ROOT가 무엇인가
+
+두 도구는 다른 축이다. ACH가 "H1이 답이다"를 알려주면, 5 Whys는 "H1의 진짜 ROOT는 H1 표면이 아니라 그 아래의 X다"를 알려준다.
+
+## 함정
+
+### "사람 탓"으로 끝나기
+
+5 Whys가 "개발자가 검토 안 했기 때문" 같은 비행동성 결론으로 끝나면 ROOT가 아니다. 더 깊이 파야 한다 — *왜 검토 절차가 작동 안 했는가*, *왜 그 라인이 검토 대상에서 빠졌는가* 등.
+
+### "외부 라이브러리 탓"으로 일찍 끝나기
+
+외부 의존 ROOT는 C(doc) 이상의 근거 (GitHub 이슈, changelog, 소스코드)로 뒷받침해야 한다. 추정만으로 외부 탓 금지 (분석 원칙).
+
+### 분기 후보가 1개만 떠오르는 경우
+
+해당 단계에서 멈추고 Fishbone 6축에서 다른 카테고리의 후보를 추가. 분기 강제 룰 위반 금지.