gh-review-triage

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 메타 및 변경 파일

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

2. 인라인 리뷰 코멘트

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

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

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에 기록하고 다음 코멘트로 이동한다.

코멘트별 제시 템플릿

### 코멘트 {번호}
- 코멘트: {원문 요약}
- 위치: {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단계: 최종 보고 형식

아래 포맷으로 답변한다.

## PR 리뷰 코멘트 판정

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

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

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

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

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

금지 사항

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