investigate

name	investigate
description	Structured root-cause debugging with scope lock. Use when hitting bugs, errors, or unexpected behavior. 4-phase: collect → analyze → hypothesize → fix.

Investigate

Position

독립 스킬. 메인 플로우(clarify→implement→verify→review→wrap)에 속하지 않음. 디버깅 상황에서 직접 호출하거나, 에이전트가 버그 시그널 감지 시 제안.

Iron Law

근본 원인 파악 없이 수정 금지. 증상만 보고 고치면 다른 곳에서 재발한다.

Flow

/investigate
│
├── Phase 1: 수집
│   ├── 에러 메시지 / 스택트레이스 전문 확보
│   ├── 재현 조건 정리 (입력, 환경, 순서)
│   ├── 언제부터 발생? (git log --oneline -20 확인)
│   └── 영향 범위 파악 (어떤 기능이 깨졌는가)
│
├── Phase 2: 분석
│   ├── 관련 코드 읽기 (에러 발생 지점 + 호출 체인)
│   ├── git blame (최근 변경이 원인인지)
│   ├── 패턴 매칭:
│   │   ├── Race condition — 공유 상태, 비동기 순서
│   │   ├── Nil propagation — null/undefined 전파 경로
│   │   ├── State corruption — 예상과 다른 상태 전이
│   │   ├── Off-by-one — 경계값, 인덱스
│   │   ├── Type mismatch — 런타임 타입 ≠ 선언 타입
│   │   └── Config/env — 환경별 차이, 누락된 변수
│   └── 재현 시도 (테스트 또는 수동)
│
├── Phase 3: 가설 (3-strike rule)
│   ├── 최대 3개 가설 수립, 가능성 높은 순 정렬
│   ├── 각 가설별 검증 방법 명시
│   ├── 검증 실행:
│   │   ├── 성공 → Phase 4
│   │   └── 실패 → 다음 가설
│   └── 3개 모두 실패 → 접근 전환 (다른 각도에서 재분석)
│
└── Phase 4: 수정
    ├── 최소 변경 원칙 (근본 원인만 수정)
    ├── 회귀 테스트 작성 (이 버그가 재발하면 잡히는 테스트)
    └── 수정 요약 리포트

Scope Lock

Phase 2에서 영향 범위를 파악한 후, 관련 모듈 외 파일 수정을 금지한다.

[Scope Lock 활성화]
수정 허용: src/auth/, src/middleware/
수정 금지: 그 외 전체

→ 범위 밖 수정이 필요하면 사용자에게 scope 확장 요청

Output

## Investigation Report

### 증상
- 에러: {에러 메시지}
- 재현: {조건}
- 발생 시점: {커밋/시간}

### 근본 원인
{원인 설명} (file:line)

### 가설 검증 이력
| # | 가설 | 결과 | 근거 |
|---|------|------|------|
| 1 | {가설1} | 확인됨 | {증거} |
| 2 | {가설2} | 기각 | {이유} |

### 수정
- 변경: {file:line — 무엇을 어떻게}
- 회귀 테스트: {테스트 파일:테스트명}

### Scope Lock
- 허용 범위: {디렉토리 목록}
- 범위 밖 수정: 없음 | {있으면 사유}

Rules

• Phase 1~3은 코드 수정 없이 읽기/분석만 한다
• Phase 4 진입 전 근본 원인을 사용자에게 보고하고 확인받는다
• 회귀 테스트 없는 수정은 완료로 인정하지 않는다 (테스트 인프라 없는 경우 제외)
• 수정 후 기존 테스트 전체 통과 확인