sj-investigate - SKILL.md Agent Skill

name: sj-investigate version: 1.0.1 description: | 체계적 루트코즈 디버깅 전문가. "고쳐줘" 전에 원인을 반드시 추적한다. 버그, 에러, 예상과 다른 동작, "왜 이러지?" 요청에 반응. 가설 수립 → 증거 수집 → 검증 루프를 강제해 추측성 수정을 방지한다. allowed-tools: - Bash - Read - Write - Edit - Glob - Grep - AskUserQuestion triggers: - /sj-investigate - /investigate

SJ Investigate — 체계적 루트코즈 디버깅

철칙: 조사 없는 수정은 없다 "빠른 수정"은 대부분 증상을 가린다. 원인이 확인될 때까지 코드를 건드리지 않는다.

Step 0: 문제 접수

현재 요청에서 문제를 파악한다. 불충분하면 AskUserQuestion 한 번:

[조사 시작]
증상: {사용자가 설명한 현상}

다음 정보가 있으면 알려주세요 (없어도 진행 가능):
- 에러 메시지 (전체)
- 재현 방법
- 언제부터 발생했는지
- 최근 변경사항

Step 1: 데이터 수집

추측하지 말고 먼저 읽는다.

# 1. 관련 로그 수집
ls -la logs/ 2>/dev/null || true
find . -name "*.log" -newer . -maxdepth 3 2>/dev/null | head -5

# 2. 최근 변경 파일 확인
git log --oneline -10 2>/dev/null
git diff HEAD~5 HEAD --name-only 2>/dev/null | head -20

# 3. 에러 패턴 검색
grep -r "error\|Error\|ERROR\|exception\|Exception" \
  --include="*.log" --include="*.txt" \
  -l 2>/dev/null | head -5

에러 메시지가 있으면 즉시 grep:

# 에러 메시지의 핵심 키워드로 검색
grep -rn "{핵심_키워드}" \
  --include="*.ts" --include="*.js" --include="*.py" --include="*.go" \
  --exclude-dir=node_modules --exclude-dir=.git | head -20

Step 2: 데이터 흐름 추적

문제가 발생하는 경로를 따라간다. 입력부터 출력까지:

데이터 흐름:
{입력} → {처리1} → {처리2} → {출력}
                         ↑
                    여기서 문제 발생 의심

각 단계에서:

입력값이 예상대로인가?
변환 과정에 버그가 있는가?
출력이 다음 단계에 맞는 형태인가?

관련 파일을 Read 툴로 직접 읽어 코드 흐름을 따라간다.

Step 3: 가설 수립 (최대 3개)

수집한 증거를 바탕으로 가설을 세운다:

## 가설 목록

### 가설 1: {제목} — 확률 {높음/중간/낮음}
근거: {어떤 증거가 이 가설을 지지하는가}
반증: {이 가설이 틀릴 수 있는 증거}
검증 방법: {어떻게 확인할 수 있는가}

### 가설 2: {제목} — 확률 {높음/중간/낮음}
...

### 가설 3: {제목} — 확률 {높음/중간/낮음}
...

확률이 높은 순서대로 검증한다. 가설 없이 수정하러 가지 않는다.

Step 4: 가설 검증

각 가설을 확률 순서로 검증:

# 가설 1 검증 예시
# 특정 조건에서 재현 시도
# 관련 테스트 실행
# 로그에서 특정 패턴 확인

검증 원칙:

가설을 CONFIRM하는 증거와 REFUTE하는 증거를 모두 찾는다
첫 번째 가설이 확인되면 나머지를 스킵하지 말고 기록만 한다
"아마도" "같아 보임"으로 수정하러 가지 않는다 — 확실한 증거 필요

Step 5: 루트코즈 확정

검증 완료 후 루트코즈를 명확히 선언한다:

## 루트코즈 확정

**원인:** {한 문장으로 정확히}

**증거:**
1. {증거1}
2. {증거2}

**왜 이 문제가 발생했는가:**
{시스템/코드/설계 관점에서 설명}

**영향 범위:**
- 직접 영향: {파일/기능}
- 잠재적 영향: {연관된 다른 영역}

루트코즈가 불확실하면 → 추가 데이터 수집 (Step 1으로 돌아감). 추측으로 수정하지 않는다.

Step 6: 수정 계획 + 실행

루트코즈가 확정됐을 때만 수정한다:

## 수정 계획

### 즉시 수정 (이번 세션)
- {파일}: {변경 내용} — 이유: {루트코즈 직접 해결}

### 예방 조치
- {코드 방어 로직 / 테스트 / 로깅 추가}

### 확인 방법
- {수정 후 검증 방법}

수정 실행 → 검증 → 필요 시 회귀 테스트 작성.

Step 7: 결과 보고 + 학습 기록

## 조사 결과

- 증상: {원래 문제}
- 루트코즈: {확정된 원인}
- 수정: {무엇을 어떻게 고쳤는가}
- 소요 시간: {조사 N분 + 수정 N분}

## 재발 방지
- {이 클래스의 버그를 막기 위해 추가할 것}

docs/sj-company/investigate-log.md에 append (다음 세션에서 같은 유형의 버그 빠르게 해결):

echo "## {날짜} — {버그 제목}
루트코즈: {원인}
수정: {방법}
패턴: {재발 방지 키워드}
" >> docs/sj-company/investigate-log.md