systematic-debugging

name	systematic-debugging
description	Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Four-phase framework ensuring understanding before attempting solutions.
allowed-tools	Read, Glob, Grep, Bash, Edit
license	MIT
metadata	{"author":"obra/superpowers","version":"1.0"}

Systematic Debugging

버그, 테스트 실패, 예상치 못한 동작에 대한 체계적 디버깅 방법론입니다.

Core Principle

"ALWAYS find root cause before attempting fixes. Symptom fixes are failure."

Mandatory Phases

Phase 1: Root Cause Investigation

1. 에러 메시지 정확히 읽기
2. 문제를 일관되게 재현
3. 최근 변경사항 확인
4. 멀티 컴포넌트 시스템에서 진단 증거 수집
5. 데이터 흐름을 역방향으로 추적

Phase 2: Pattern Analysis

1. 작동하는 예시 찾기
2. 레퍼런스와 비교
3. 차이점 식별
4. 의존성 이해

Phase 3: Hypothesis Testing

1. 구체적인 가설 수립
   - "X가 Y 때문에 발생한다고 생각됨"

2. 최소한의 테스트로 검증
   - 한 번에 하나의 변수만 변경

3. 과학적으로 결과 검증
   - 가설이 틀렸다면 다음 가설로

Phase 4: Implementation

1. 실패하는 테스트 케이스 작성
2. 단일 수정 구현
3. 결과 검증
4. 3번 실패 시 중단
   → 아키텍처 문제 가능성 검토

Critical Rules

규칙	설명
순차 진행	단계를 건너뛰지 않음
단일 수정	동시에 여러 수정 금지
3회 실패 시 중단	아키텍처 검토 필요

Red Flags - 프로세스 포기 징후

❌ "일단 빠르게 고치고..."
❌ "아마 여기가 문제인 것 같아서..."
❌ "시간이 없어서 그냥..."
❌ "재현은 안되지만 고쳐봤어요"

Debugging Template

## 문제
[증상 설명]

## 재현 단계
1. [단계 1]
2. [단계 2]
→ [예상 결과] vs [실제 결과]

## Phase 1: 조사
- 에러 메시지: [정확한 메시지]
- 최근 변경: [관련 커밋/변경]
- 데이터 흐름: [추적 결과]

## Phase 2: 패턴 분석
- 작동 케이스: [예시]
- 차이점: [식별된 차이]

## Phase 3: 가설
1. 가설: [내용]
   테스트: [방법]
   결과: [결과]

## Phase 4: 수정
- 수정 내용: [변경사항]
- 테스트: [검증 방법]
- 결과: ✅/❌

Evidence-Based Results

체계적 디버깅 적용 시:
- 문제 해결 시간: 2-3시간 → 15-30분
- 재발 방지: 근본 원인 해결로 재발 감소
- 학습 효과: 시스템 이해도 향상

Best Practices

1. 증거 수집: 로그, 스택 트레이스, 재현 단계 문서화
2. 최소 변경: 한 번에 하나만 변경하고 테스트
3. 원복 준비: 변경 전 상태로 돌릴 수 있게 준비
4. 기록 유지: 시도한 것과 결과 문서화