---
name: gh-review-triage
description: GitHub Pull Request 링크를 입력받아 리뷰 코멘트(라인 코멘트/리뷰 코멘트/일반 코멘트)를 수집하고, 코멘트별 초안 판정을 만든 뒤 수동 텍스트 승인 루프로 순차 확정한다. 실제 반영이 수행되면 마지막에 계획 문서 변경분까지 동기화할 때 사용한다.
---

# GH Review Triage

PR 리뷰 코멘트를 실행 가능한 액션으로 분류하는 작업용 스킬이다.
결과를 한 번에 확정하지 말고, 코멘트마다 `초안 판정 -> 사용자 승인 -> 최종 판정`을 반복한다.

핵심 원칙:

1. 코멘트 요약보다 판단 근거를 우선 제공한다.
2. `반영` 판단이면 반드시 어떻게 반영할지까지 제시한다.
3. 코드베이스/컨벤션/테스트 맥락과 충돌하는 의견은 무비판 수용하지 않는다.
4. 정보가 부족하면 추측하지 말고 `미반영(판단 보류)`로 분리한다.
5. 사용자 의견/승인은 코멘트 단위로 순차 수집한다.
6. 실제 반영이 발생하면 종료 전에 계획 문서를 최신 상태로 갱신한다.

## 사용법

- 호출 예시:
  - `/gh-review-triage https://github.com/org/repo/pull/123`
  - `/gh-review-triage https://github.com/org/repo/pull/123 docs/plan/feature-x.md`
- `$ARGUMENTS`가 없으면 PR 링크를 요청하고 중단한다.
- 지원 URL:
  - `https://github.com/{owner}/{repo}/pull/{number}`
  - `http://github.com/{owner}/{repo}/pull/{number}`
- PR URL 뒤에 추가 인자가 있으면 계획 문서 경로 후보(`PLAN_DOC_PATH`)로 처리한다.

## 수동 텍스트 승인 루프 규칙

- 의견/승인 요청은 항상 수동 텍스트로 진행한다.
- 허용 입력은 아래 3개만 사용한다.
  1. `승인`: 현재 코멘트의 권장 판정/반영안 확정
  2. `승인 안 함`: 현재 코멘트 권장안을 확정하지 않음
  3. `수정 지시: <내용>`: 지시를 반영해 초안을 수정한 뒤 재승인
- `Other(다른 지시)` 텍스트가 입력되면 `수정 지시`와 동일하게 처리한다.
- 입력이 불명확하면 확정하지 말고 허용 입력(`승인`, `승인 안 함`, `수정 지시: ...`)으로 재입력을 요청한다.

## 실행 워크플로우

### 1단계: 입력/접근성 확인

1. `$ARGUMENTS`에서 PR URL을 추출한다.
2. URL 패턴이 맞지 않으면 올바른 예시를 제시하고 중단한다.
3. URL에서 `OWNER`, `REPO`, `PR_NUMBER`를 추출한다.
4. PR URL 뒤 추가 인자가 있으면 `PLAN_DOC_PATH`로 저장한다.
5. `gh` 인증/권한을 점검한다.
   - 실패 시 `gh auth status` 결과와 함께 접근 권한 문제를 안내하고 중단한다.

### 2단계: 리뷰 코멘트 수집

아래 데이터를 수집한다.

1. PR 메타 및 변경 파일

```bash
gh pr view "$PR_URL" --json number,title,baseRefName,headRefName,author,files,reviews,comments
```

2. 인라인 리뷰 코멘트

```bash
gh api "repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments?per_page=100" --paginate
```

3. PR 일반 코멘트(이슈 코멘트)

```bash
gh api "repos/$OWNER/$REPO/issues/$PR_NUMBER/comments?per_page=100" --paginate
```

중복 코멘트(동일 작성자 + 동일 본문 + 동일 시각)는 제거한다.

### 3단계: 코멘트 정규화

각 코멘트를 아래 구조로 정리한다.

- `id`
- `type` (`INLINE_REVIEW`, `PR_REVIEW`, `GENERAL`)
- `reviewer`
- `file:line` (있으면)
- `body`
- `created_at`

코멘트가 0개면 "리뷰 코멘트 없음"으로 보고하고 종료한다.

### 4단계: 코멘트별 초안 판정

각 코멘트마다 먼저 초안 판정을 만든다.

- 초안 판정: `반영` 또는 `미반영`
- 근거 부족 시: `미반영(판단 보류)` + 추가 확인사항 명시

판단 기준:

- 반영
  - 기능/정합성/버그/보안/데이터 무결성 문제를 지적한다.
  - 성능/동시성/장애 가능성 등 운영 리스크를 실질적으로 낮춘다.
  - 테스트 누락/회귀 방지 관점에서 타당하다.
  - 프로젝트 컨벤션/아키텍처와 일치한다.

- 미반영
  - 개인 취향 수준의 스타일 제안이고 기존 컨벤션과 충돌한다.
  - 사실관계가 틀렸거나 현재 코드 전제와 맞지 않는다.
  - 적용 시 부작용이 이득보다 크다.
  - 이미 다른 변경으로 해결되었다.

### 5단계: 코멘트별 승인 루프 (순차)

모든 코멘트를 한 번에 묻지 않는다. 코멘트 1부터 순서대로 반복한다.

1. 현재 코멘트의 초안 판정과 근거를 제시한다.
2. 초안이 `반영`이면 권장 반영안(대상/변경/검증)까지 같이 제시한다.
3. 수동 텍스트로 `승인 / 승인 안 함 / 수정 지시: ...` 중 하나를 받는다.
4. 선택 처리:
   - `승인`: 현재 초안을 최종 판정으로 확정
   - `승인 안 함`: 현재 코멘트를 `미반영(사용자 미승인)`으로 확정
   - `Other(다른 지시)` 또는 `수정 지시: ...`: 지시를 반영해 초안 수정 후 동일 방식으로 재승인
5. 확정 결과를 `decision_log`에 기록하고 다음 코멘트로 이동한다.

#### 코멘트별 제시 템플릿

```markdown
### 코멘트 {번호}
- 코멘트: {원문 요약}
- 위치: {file:line 또는 N/A}
- 초안 판단: {반영 / 미반영 / 미반영(판단 보류)}
- 근거:
  - {근거 1}
  - {근거 2}

- 권장 반영안: (초안이 반영일 때만)
  - 대상: {파일/함수}
  - 변경: {구체 변경}
  - 검증: {테스트/검증 방법}

**승인 요청**
- 수동 텍스트로 `승인`, `승인 안 함`, `수정 지시: ...` 중 하나를 입력
```

### 6단계: 범위 초과/충돌 승인 게이트

아래 상황이면 즉시 별도 승인 질문을 띄운다.

- 코멘트 반영을 위해 요청 범위를 넘는 리팩토링이 필요한 경우
- 다수 코멘트가 서로 충돌하여 선택이 필요한 경우
- 현재 로컬 코드와 PR HEAD가 달라 정확한 판단이 어려운 경우

승인 게이트 질문도 같은 수동 텍스트 승인 루프를 사용한다.

- 기본 선택: `승인`, `승인 안 함`
- `Other(다른 지시)` 또는 `수정 지시: ...` 입력 시 대안안을 갱신해 재질의

### 7단계: 반영 완료 후 계획 문서 업데이트

`final_decisions`에서 최종 판단이 `반영`이고 실제 반영 작업이 수행된 항목이 1건 이상이면, 종료 전에 계획 문서를 동기화한다.

1. 계획 문서 경로 확보:
   - `PLAN_DOC_PATH`가 있으면 사용
   - 없으면 수동 텍스트로 아래 중 하나를 받는다.
     - `계획 문서 경로: <path>`
     - `계획 문서 없음`
2. `계획 문서 없음`이 입력되면 동기화를 건너뛰고 사유를 `plan_doc_update_log`에 기록한다.
3. 경로가 있으면 파일 존재를 확인한다.
   - 없으면 경로 재입력을 1회 요청하고, 재시도 후에도 없으면 동기화를 건너뛴다.
4. 문서 업데이트 규칙:
   - `PR 리뷰 반영 내역` 섹션이 있으면 해당 섹션에 이번 반영분을 추가
   - 섹션이 없으면 문서 끝에 `## PR 리뷰 반영 내역 ({YYYY-MM-DD})` 섹션을 생성
5. 반영된 코멘트별로 아래 정보를 기록한다.
   - 코멘트 ID/요약
   - 실제 변경 파일/함수
   - 검증 결과(테스트/수동 확인)
   - 후속 작업(있으면)
6. 동기화 결과(`UPDATED / SKIPPED / FAILED`)를 `plan_doc_update_log`에 기록하고 최종 보고에 포함한다.

### 8단계: 최종 보고 형식

아래 포맷으로 답변한다.

```markdown
## PR 리뷰 코멘트 판정

### 코멘트 {번호}
- 코멘트: {원문 요약}
- 위치: {file:line 또는 N/A}
- 초안 판단: {반영 / 미반영 / 미반영(판단 보류)}
- 사용자 결정: 승인 / 승인 안 함 / Other·수정 지시 반영 후 승인
- 최종 판단: 반영 / 미반영
- 근거:
  - {근거 1}
  - {근거 2}

- 반영 방법: (최종 판단이 반영일 때만)
  - 대상: {파일/함수}
  - 변경: {구체 변경}
  - 검증: {테스트/검증 방법}

### 코멘트 {번호}
...

## 종합
- 반영: {n}건
- 미반영: {n}건
- 판단 보류: {n}건 (필요 정보: {요약})
- 사용자 미승인: {n}건
- 계획 문서 업데이트: UPDATED / SKIPPED / FAILED

## 계획 문서 업데이트
- 대상 문서: {경로 또는 N/A}
- 동기화 건수: {n}
- 메모: {갱신 내용 요약 또는 스킵/실패 사유}
```

## 금지 사항

- 근거 없이 "느낌상 반영"으로 판단
- `반영` 판단인데 구체적인 변경 방법/검증 계획을 누락
- 리뷰어 권위만으로 무비판 수용
- 여러 코멘트를 묶어 한 번에 승인 요청
- 실제 반영이 있었는데 계획 문서 동기화 없이 종료