---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

# Systematic Debugging

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
```

Phase 1 전 수정 금지.

## 4단계 프로세스

1. **Root Cause**: 에러 정독, 재현, 변경 확인, 경계 증거 수집, 흐름 역추적
2. **Pattern Analysis**: 유사 코드 탐색, 레퍼런스 완독, 차이점 목록화
3. **Hypothesis**: 단일 가설, 최소 변경 검증. 실패 시 새 가설
4. **Implementation**: 실패 테스트 먼저, 루트 원인만 수정. 3회+ 실패 시 아키텍처 검토

## Red Flags — Phase 1 복귀

- "빠르게 고치고 나중에 조사"
- "X 바꾸면 될 것 같아"
- "한 번만 더" (2회+ 실패)
- 수정마다 다른 곳 새 문제

## Common Rationalizations

- "긴급, 생략" → Systematic > thrashing
- "단순 문제" → 루트 원인 존재
- "여러 수정 동시에" → 원인 특정 불가
- "증상이 보여" → 증상 ≠ 루트 원인
- "한 번만 더" → 3+회 = 아키텍처 문제

## AI 에이전트 디버깅 (langsmith-fetch 연동)

- AI 에이전트 관련 버그 디버깅 시, `/langsmith-fetch`로 LangSmith 트레이스 조회 가능
- dispatch.py 에이전트 실행 트레이스 분석, 에러 패턴 감지, 성능 병목 식별에 활용
- LangSmith 미사용 환경에서는 보류 가능
- 참조: `/langsmith-fetch` 스킬 (LangSmith API 기반 트레이스 조회/분석)

> 상세 예제 및 기법은 `SKILL-EXAMPLES.md` 참조