Systematic Debugging

---
name: systematic-debugging
description: Root-cause-first debugging methodology. Use when encountering any bug, test failure, or unexpected behavior BEFORE proposing fixes. Prevents random fix attempts that waste time and create new bugs.
metadata:
  author: misskim
  version: "1.0"
  origin: Concept from obra/superpowers systematic-debugging, adapted for our workflow
---

# Systematic Debugging

## 철칙

```
근본 원인 파악 없이 수정 시도 절대 금지
```

## 4단계 프로세스

### Phase 1: 근본 원인 조사

**수정 시도 전에 반드시:**

1. **에러 메시지 정독** — 스택 트레이스 전체 읽기, 줄 번호/파일 경로 기록
2. **재현** — 일관되게 트리거 가능한가? 정확한 단계는?
3. **최근 변경 확인** — git diff, 최근 커밋, 새 의존성, 설정 변경
4. **데이터 흐름 추적** — 잘못된 값이 어디서 시작되는가? 역추적

**다중 컴포넌트 시스템일 때:**
각 경계에 진단 로그 추가 → 한 번 실행 → 어디서 깨지는지 확인 → 그 컴포넌트만 조사

### Phase 2: 패턴 분석

1. **작동하는 예제 찾기** — 같은 코드베이스에서 유사한 작동 코드
2. **참조와 비교** — 패턴 구현 시 참조 문서 완전히 읽기 (훑어보기 금지!)
3. **차이점 식별** — 작동/비작동 간 모든 차이 나열
4. **의존성 파악** — 필요한 다른 컴포넌트, 설정, 환경

### Phase 3: 가설 검증

1. **단일 가설 수립** — "X가 근본 원인이다. 왜냐하면 Y"
2. **최소 변경으로 테스트** — 한 번에 하나만 변경
3. **검증** — 작동하면 Phase 4, 아니면 새 가설
4. **모르면 모른다고 인정** — 추측하지 말 것

### Phase 4: 구현

1. **실패 테스트 케이스 작성** — 수정 전에 먼저
2. **단일 수정 구현** — 근본 원인만 해결, "김에 같이" 개선 금지
3. **검증** — 테스트 통과? 다른 테스트 깨지지 않음?
4. **3번 이상 수정 실패 시 → 아키텍처 의심**
   - 매 수정마다 새로운 문제 발견?
   - "대규모 리팩토링"이 필요하다면?
   - **STOP** — 근본 설계가 잘못된 것. 주인님과 논의.

## 🚨 위험 신호 — 즉시 멈추고 Phase 1로

- "일단 X 바꿔보고 되는지 보자"
- "여러 변경을 한꺼번에 테스트"
- "빠른 수정, 나중에 조사"
- "대충 이게 문제인 것 같은데"
- "수동으로 확인했으니 될 거야"
- 조사 없이 수정안 제안
- 2번 이상 수정 시도 실패

## 합리화 방지

| 핑계 | 현실 |
|------|------|
| "간단한 문제라 프로세스 불필요" | 간단한 버그에도 근본 원인 있음 |
| "급해서 프로세스 따를 시간 없음" | 체계적 디버깅이 추측보다 빠름 |
| "일단 이것부터 시도" | 첫 수정이 패턴을 결정함 |
| "참조 문서가 너무 길어" | 부분 이해 = 버그 보장 |