By description: 버그 리포트나 이슈를 받아 재현 → 원인 분석 → 수정 후보 제시까지 디버깅 사이클을 자동화합니다. argument-hint: "<증상 설명 또는 이슈 번호>" user-invocable: true
Investigate — 버그 조사 워크플로우
증상 설명 또는 GitHub Issue 번호를 받아 재현 → 원인 격리 → 수정 후보 제시까지 수행한다.
Phase 1: 입력 분류
- 숫자 → GitHub Issue:
gh issue view $ARGUMENTS --comments - 자연어 → 증상 설명으로 간주하고 바로 Phase 2.
Phase 2: 재현
- Explore 서브에이전트로 관련 코드 탐색 (에러 메시지·클래스명 키워드 검색, 관련 테스트·최근 커밋 확인) — 메인 컨텍스트 보존.
- 증상을 재현하는 실패하는 테스트를 먼저 작성하고 실패를 확인한다:
cd <package-dir> && uv run pytest <test-file>::<test-name> -x -v - 재현 불가(환경 의존·타이밍)면 사유 기록 후 정적 분석으로 대체.
Phase 3: 원인 격리
가설 없이 코드를 수정하지 않는다 — 가설 목록(가설·검증 방법·가능성)을 세우고 가능성 순으로 검증하여 근본 원인(코드 위치 + 로직)·발생 경위·검증 증거를 확정한다.
Phase 4: 수정 후보 + 보고
근본 원인에 대해 수정 방안 1-3개(변경 범위·트레이드오프·영향)를 도출하고, 아래 형식을 반드시 텍스트로 화면에 출력한다:
## 조사 결과
### 증상
{증상 요약}
### 근본 원인
{근본 원인 설명 — 코드 위치 포함}
### 수정 후보
| # | 방안 | 변경 범위 | 영향 |
|---|------|----------|------|
| 1 | {방안 1} | {파일 목록} | {영향} |
### 재현 테스트
{테스트 파일 경로, 또는 "재현 테스트 불가 — 사유"}
4-3. 다음 액션
원인 + 해결방법 모두 식별 (default): 사용자 질의 없이 즉시 진행 — 1) /plan-issues로 조사 결과를 GitHub Issue으로 변환, 2) /process-ticket --auto-merge {이슈 번호}로 구현·CI·머지 자동화 (워크트리는 process-ticket Phase 3이 생성).
원인 또는 해결방법 미확정: 사용자 질의로 분기 — 추가 조사 / 수정 진행(방안 번호) / 이슈 생성 / 종료.
규칙
- 재현 테스트 작성 선행 — 수정 후 해당 테스트 통과 확인.
- 코드 탐색은 Explore 서브에이전트로 실행.
- 수정 범위 최소화 — 버그 수정에 리팩터링 섞지 않음.
uv run접두사 필수. 루트에서 직접 실행 금지 — 패키지 디렉토리 내에서 실행.
$ARGUMENTS