---
name: bug-report-to-fix
description: 사용자가 버그, 불명확한 증상, 스크린샷, 로그 또는 재현 정보를 주고 진단이나 수정을 요청할 때 사용합니다. 사실과 추정을 분리해 재현·원인을 먼저 조사하고, 요청 증상과 직접 관련된 원인 및 필수 변경 범위를 제시해 별도 승인받은 뒤 수정·검증합니다. 조사 중 발견한 별도 버그, 독립 리팩터링과 새 동작은 별도 범위로 분리합니다.
---

# 버그 조사와 수정

## 출력 언어

사용자가 출력 언어를 명시적으로 지정하면 해당 언어를 사용합니다. 지정하지 않으면 이 스킬이 만드는 모든 사용자 대상 출력, 문서, 프롬프트, 보고서, 계획, 스펙 및 기타 산출물을 한국어로 작성합니다. 제목, 섹션, 레이블, 표, 체크리스트, 다이어그램과 템플릿에도 같은 언어를 사용합니다. 코드, 명령어, 파일 경로, 식별자, API 이름, 모델 ID, 프로토콜 이름과 필수 고유명사는 번역하지 않습니다.

## 진행 흐름

1. 보이는 증상, 기대 결과, 확인된 환경과 원인 추정을 분리합니다.
2. 저장소, 로그, 최근 변경과 테스트에서 재현에 필요한 사실을 먼저 조사합니다.
3. 사용자만 답할 수 있고 원인 분기가 실제로 달라지는 최소 질문만 합니다.
4. 사용자의 요청 동사를 기준으로 실행 범위를 정합니다.
   - `진단해줘`, `원인을 찾아줘`, `검토해줘`: 조사와 근거 보고까지만 수행합니다.
   - `고쳐줘`, `수정해줘`, `해결해줘`: 현재 요청과 직접 관련된 원인 및 필수 변경을 읽기 전용으로 조사하고, 변경 파일·동작·검증·제외 범위를 제시해 별도 승인받은 뒤 재현·수정·검증합니다.
   - 데이터 손실, 보안, 배포, 권한 또는 외부 영향 행동: 해당 위험 행동 직전에만 별도 승인을 받습니다.
5. 승인 뒤 조사 중 스킬 소스나 여러 파일의 변경이 필요해져도 승인된 범위 안에서 요청 증상을 고치는 데 필수라면 계속 구현합니다. 승인 범위를 벗어나거나 직접 관련되지 않은 문제와 선택적 개선은 수정하지 않고 근거와 영향을 알린 뒤 범위 확장 승인받습니다.
6. 사용자가 별도 Codex 작업 생성을 명시적으로 요청한 경우에만 `start-implementation-thread`를 적용합니다.

## 조사 뒤 승인받고 구현 계속

다음 파일을 바꿔 스킬의 행동, 라우팅, 도구 사용, 출력 계약 또는 트리거 조건에 영향을 주는 경우에도 먼저 변경 범위를 제시하고 별도 승인받습니다. 승인 뒤에는 조사 결과를 문서로만 남기고 멈추지 않고 승인 범위의 구현·검증을 완료합니다.

- 스킬의 `SKILL.md`
- 스킬의 `agents/openai.yaml` 등 에이전트 메타데이터
- 스킬이 사용하는 `scripts/`, `references/`, `assets/`의 실행 규칙 또는 계약
- 플러그인 안에서 여러 스킬의 호출 순서나 등급 판정을 바꾸는 공통 규칙

- 변경 전 관련 규칙과 호출 경로를 조사합니다.
- 조사 결과와 수정 방향, 변경 파일, 검증과 제외 범위를 알리고 승인 카드를 제시한 뒤 현재 턴을 끝냅니다.
- 뒤이은 별도 승인 메시지를 받은 다음 턴부터 파일을 수정합니다.
- 필요한 문서는 구현과 함께 갱신하되, 문서 작성·검토를 구현 전 승인 게이트로 사용하지 않습니다.
- 실제 선택에 따라 서로 다른 제품 동작이 생기면 그 선택만 질문합니다.
- 외부·비가역 행동은 해당 행동 직전에만 확인합니다.

## 관련성 판정

한 번의 범위 승인 뒤 추가 승인 없이 같은 구현 단위에서 계속할 수 있는 관련 변경은 다음 조건을 모두 만족해야 합니다.

1. 사용자가 보고한 증상, 재현 경로 또는 명시한 완료 조건과 직접 연결됩니다.
2. 확인된 원인을 제거하거나 같은 버그의 회귀를 막는 데 필요합니다.
3. 독립적으로 배포하거나 설명할 별도 기능·정책 변경이 아닙니다.

다음은 관련 없는 별도 범위로 보고 수정 전에 승인을 받습니다.

- 조사 중 우연히 발견했지만 요청 증상과 인과관계가 없는 다른 버그
- 현재 버그 수정 없이도 별도로 수행할 수 있는 리팩터링, 성능 개선과 정리
- 사용자가 요청하지 않은 기능, 출력 계약, 공개 API 또는 의존성 변경
- 현재 재현을 고치는 데 필요하지 않은 주변 파일의 일괄 수정

관련성 판단이 애매하면 먼저 가장 작은 재현과 원인 경로로 범위를 좁힙니다. 그래도 독립 변경인지 결정되지 않으면 수정 전에 사용자에게 관련성 근거와 선택지를 제시합니다.

## 사실 분류

- `관찰`: 화면, 로그, 오류 메시지와 재현 결과
- `확인된 환경`: 실제로 테스트한 플랫폼·버전·설정
- `미확인 환경`: 아직 테스트하지 않은 범위
- `원인 후보`: 근거와 반증 방법이 있는 가설
- `확인된 원인`: 재현이나 코드 경로로 검증한 원인

`iOS에서 확인됨`을 `iOS 전용`으로 바꾸지 않습니다. 스크린샷에 보이는 현상을 내부 원인으로 단정하지 않습니다.

## 수정 원칙

- 가장 작은 안전한 수정으로 확인된 원인을 제거합니다.
- 증상만 숨기는 변경과 원인을 고치는 변경을 구분합니다.
- 수정 전 재현이나 실패 테스트를 확보할 수 있으면 먼저 확보합니다.
- 수정 후 같은 재현, 관련 테스트, 로그 또는 가능한 가장 가까운 검증을 수행합니다.
- 검증하지 못한 플랫폼이나 조건은 해결됐다고 보고하지 않습니다.

## 문서와 승인

버그 리포트 파일은 사용자가 요청했거나 장기 재개에 실제 필요할 때만 만듭니다. 문서가 필요하면 `팩트와 근거`, `실행 계획`, `위험과 열린 질문`을 구현과 병행해 기록합니다.

조사 중 발견한 별도 문제의 범위 확장 여부가 승인·취소 두 선택으로 충분하고 열린 질문이 없으면 `../../references/workflow-confirmation-ui.md`에 따라 버튼형 승인 카드를 사용합니다. 위험 행동의 네이티브 권한 승인은 이 카드로 대체하지 않습니다.

문서 작성 자체가 승인된 구현 범위에 포함되지 않았다면 읽기 전용 조사 결과만 제시합니다. 최초 수정 요청을 실행 승인으로 간주하지 않으며, 변경 범위를 제시한 뒤 별도 승인받아 구현·검증합니다. 별도 Codex 작업 생성은 사용자가 요청하고 범위를 승인했을 때만 수행하며, 외부·비가역 행동은 직전에 다시 확인합니다.

## 완료 점검

- [ ] 관찰과 원인 추정을 분리했는가
- [ ] 확인된 환경과 미확인 환경을 구분했는가
- [ ] 저장소에서 알 수 있는 사실을 사용자에게 묻지 않았는가
- [ ] 사용자의 수정 요청을 범위 제시 뒤 별도 승인 없이 실행하지 않았는가
- [ ] 승인 뒤에는 승인된 구현·검증 범위를 완료했는가
- [ ] 요청 증상과 직접 관련된 변경만 같은 작업에서 구현·검증했는가
- [ ] 조사 중 발견한 별도 버그와 선택적 개선은 승인 없이 수정하지 않았는가
- [ ] 문서 승인 게이트를 추가하지 않았는가
- [ ] 수정 후 실제 재현 또는 가장 가까운 검증을 수행했는가