외부 기여자 PR 완료 처리

트리거

• 명시 호출만: 작업지시자가 "외부 PR #N 완료 처리", "PR #N merge 후 정리", "external-pr-complete 실행"을 지시한 경우
• external-pr-review에서 merge/cherry-pick 가능으로 검토되고, 작업지시자가 실제 반영 완료 또는 완료 처리 진행을 명시한 경우

사전 조건

• 대상은 외부 기여자 PR이다. 내부 task PR(publish/task{N})에는 사용 금지
• mydocs/pr/pr_{N}_review.md가 존재하거나, 처리 근거가 PR/Issue 코멘트로 재구성 가능해야 한다
• PR이 GitHub merge 완료 상태이거나, maintainer cherry-pick/수동 반영 commit이 확인되어야 한다
• 관련 Issue close는 작업지시자 승인 후에만 수행한다
• gh CLI 인증

직접 반영 기준

• mydocs/pr/pr_{N}_review.md, mydocs/pr/pr_{N}_report.md, mydocs/pr/archives/** 같은 외부 PR 운영 기록만 변경하면 별도 PR을 만들지 않고 대상 통합 브랜치에 직접 커밋/푸시한다.
• 직접 반영은 push까지 완료해야 한다. 운영 기록 커밋을 로컬 base branch에만 남기지 않는다.
• Skill, 매뉴얼, 코드, 빌드 설정, 앱 동작, workflow 정책 변경이 함께 있으면 직접 반영하지 말고 일반 Issue/브랜치/PR 절차로 분리한다.
• 직접 반영 전 git pull --ff-only가 실패하거나 대상 브랜치가 diverged 상태면 중단하고, 운영 기록 커밋만 재정렬할지 작업지시자에게 확인한다.

절차

1. 완료 상태 수집

   gh pr view {N} --json number,title,state,author,baseRefName,headRefName,isCrossRepository,mergedAt,mergeCommit,comments,commits,files,body,url
   gh pr checks {N}
   

   • PR state, merge commit, head SHA, base branch, 작성자, 연결 이슈, 기존 코멘트를 확인
   • cherry-pick/수동 반영이면 작업지시자 또는 git log로 반영 commit SHA를 확인
2. 관련 Issue 식별
   • PR 본문 closes #N, Related: #N, review 문서, 작업지시자 지시에서 후보를 찾음
   • 후보가 여러 개거나 Related만 있고 완료 여부가 애매하면 close 전에 작업지시자에게 확인
   • 이슈 확인:

     gh issue view {ISSUE} --json number,title,state,comments,url
     

3. 완료 보고서 작성 또는 갱신: mydocs/pr/pr_{N}_report.md
   • 표준 섹션:
     • PR 정보 (번호, 작성자, base/head, 연결 이슈)
     • 처리 결정 (merge / cherry-pick 통합 / close)
     • 반영 commit (PR head, merge commit 또는 cherry-pick commit)
     • 메인테이너 후속 보완/충돌 해소 내역
     • 검증 결과
     • 첫 기여 여부와 기여자 커뮤니케이션 요지
     • PR 완료 코멘트 등록 여부/링크/요지
     • Issue 코멘트/close 여부/링크/요지
     • 남은 리스크와 후속 이슈
   • PR/Issue 코멘트 초안 전문은 보고서에 쓰지 않는다. 링크와 요지만 기록한다
4. 응답용 완료 코멘트 초안 작성
   • 사용자 응답에만 PR 완료 코멘트 초안, Issue 완료 코멘트 초안 섹션으로 제시
   • 첫 기여자라면 환영과 감사를 포함하되, 칭찬은 구체적 기여 사실에 붙인다
   • 칭찬 후보는 문제 정의, 작은 변경 범위, 기존 구조 존중, 테스트/샘플 보강, maintainer 피드백 반영, 문서화처럼 실제 확인한 항목만 사용한다
   • maintainer가 충돌 해소, follow-up commit, cherry-pick 보정, 검증 보완을 했다면 숨기지 말고 비난 없이 사실로 적는다
   • PR 범위를 넘는 후속 항목이 남았으면 별도 Issue/내부 타스크 링크 또는 예정 문구를 completion comment에 짧게 포함한다
   • GitHub PR/Issue 참조 표기는 아래 "GitHub 참조 표기 규칙"을 따른다
   • 실제 수행한 검증만 적고, 실행하지 않은 검증은 쓰지 않는다
5. 작업지시자 승인 후 GitHub 처리
   • 승인 전에는 GitHub 코멘트 등록, issue close, branch cleanup을 하지 않는다
   • 승인 후 필요 시:

     gh pr comment {N} --body-file /tmp/pr_{N}_complete_comment.md
     gh issue comment {ISSUE} --body-file /tmp/issue_{ISSUE}_complete_comment.md
     gh issue close {ISSUE}
     

6. 처리 완료 문서 보관 이동

   git mv mydocs/pr/pr_{N}_review.md mydocs/pr/archives/
   git mv mydocs/pr/pr_{N}_review_impl.md mydocs/pr/archives/  # 존재 시
   git mv mydocs/pr/pr_{N}_report.md mydocs/pr/archives/
   

7. 직접 반영 준비

   BASE_BRANCH={PR base branch}
   git fetch origin --prune
   git checkout "$BASE_BRANCH"
   git pull --ff-only
   git status --short
   git diff --name-only --cached
   git diff --name-only
   

   • 변경 파일이 mydocs/pr/** 운영 기록으로만 제한되는지 확인한다.
   • 다른 파일이 섞이면 commit/push를 중단하고 일반 작업 PR로 분리한다.
8. 단일 커밋 후 직접 push

   git add mydocs/pr/
   git commit -m "PR #{N} 완료 처리: {요약}"
   git push origin "$BASE_BRANCH"
   

   • push 실패 또는 non-fast-forward가 발생하면 강제 push하지 말고 작업지시자에게 보고한다.

GitHub 참조 표기 규칙

• PR 완료 코멘트와 Issue 완료 코멘트 모두 GitHub PR/Issue 참조 토큰을 한글 조사와 붙여 쓰지 않는다.
• #328으로, #132를, PR #328은처럼 쓰지 말고 #328 반영으로, #132 이슈를, PR #328 반영은처럼 참조 토큰 뒤를 공백, 문장 부호, 또는 별도 명사로 분리한다.
• 여러 대상을 함께 적을 때는 PR #328 및 Issue #132처럼 각 참조 토큰을 독립적으로 둔다.

PR 완료 코멘트 초안 원칙

• 목적은 merge 후 공개 완료 안내다. merge 전 검토 의견이나 사전 승인 요청으로 쓰지 않는다
• edwardkim/rhwp 방식처럼 다음 정보를 짧게 남긴다:
  • 반영 완료 선언
  • 반영 방식과 대상 branch
  • merge/cherry-pick commit SHA
  • 충돌 해소 또는 메인테이너 후속 보완 내역
  • 실행한 검증 명령
  • 시각/수동 판정 결과가 있으면 포함
  • 첫 기여자 환영 여부
  • 기여 감사와 구체적 기여 포인트
  • 남은 내부 후속 Issue/타스크 또는 다음 PR 안내가 있으면 한 줄로 포함
• 첫 기여자에게는 "첫 외부 기여라 더 반갑다"는 환영을 넣되, 프로젝트가 실제로 얻은 효과를 함께 적는다
• maintainer 후속 보완이 있었던 경우 "PR 내용 반영 후 maintainer 측에서 ..."처럼 사실 중심으로 적고, 기여자의 실패처럼 표현하지 않는다
• 다음 기여 안내는 실행 가능한 내용이 있을 때만 쓴다. 예: base branch, smoke test, 샘플 파일, 문서 위치

PR 완료 코멘트 템플릿

메인테이너 검증 및 반영 완료했습니다.

- PR #{N} 반영: `{base}`에 {merge/cherry-pick/수동 반영}했습니다.
- 반영 commit: `{sha}`
- {충돌 해소 또는 메인테이너 후속 보완 내역. 없으면 생략}
- {수동/시각/설치본 판정 결과. 없으면 생략}

검증:

```text
{실제로 실행한 검증 명령과 결과}
```

기여 감사합니다. {이번 PR의 구체적 기여 의미 또는 첫 기여 환영 문장}
{다음 PR에 도움이 되는 짧은 안내 또는 별도 후속 Issue/타스크 링크. 없으면 생략}

Issue 완료 코멘트 초안 원칙

• Issue에는 "무엇으로 해결됐는지"와 "어떤 검증으로 닫는지"를 남긴다
• Issue 코멘트는 해결 근거 중심으로 쓴다. 기여자 칭찬과 환영 문구는 PR 완료 코멘트에 둔다
• PR이 Related만 사용했어도 작업지시자가 close를 승인하면 수동으로 comment 후 close한다
• 여러 issue가 관련되면 각 issue별로 해결 범위가 맞는지 분리해서 작성한다

Issue 완료 코멘트 템플릿

PR #{N} 반영 및 {필요 시 메인테이너 후속 보완}으로 해결되었습니다.

반영 내용:

- {핵심 해결 내용 1}
- {핵심 해결 내용 2}
- `{base}` 반영 commit: `{sha}`

검증:

```text
{실제로 실행한 검증 명령과 결과}
```

이 이슈는 완료 처리합니다.

판단 기준

• PR이 아직 merge/반영되지 않았으면 완료 코멘트를 작성하지 말고 external-pr-review 단계로 돌려보낸다
• issue close는 PR merge만으로 자동 실행하지 않는다. 작업지시자 승인과 해결 범위 확인이 필요하다
• 연결 이슈가 Related인지 Closes인지에 따라 자동 close 기대 여부를 구분하되, 실제 close 전 상태를 확인한다
• cherry-pick이면 원 PR head SHA와 반영 commit SHA를 모두 보고서에 기록한다
• 완료 코멘트 전문은 응답에만 제시하고, pr_{N}_report.md에는 링크와 요지만 남긴다
• 외부 PR 운영 기록만 바뀌면 별도 PR을 만들지 않는다. 직접 커밋 후 대상 통합 브랜치에 push까지 완료한다

검증

• pr_{N}_report.md에 처리 결정, commit SHA, 검증 결과, PR/Issue 처리 요지가 기록됨
• 응답에 PR 완료 코멘트 초안과 필요한 Issue 완료 코멘트 초안이 제시됨
• 승인 후 실제 GitHub 코멘트 URL과 issue close 상태가 확인됨
• 처리 완료 문서가 mydocs/pr/archives/로 이동됨
• 직접 반영 시 git status --short --branch에 대상 branch의 local-only ahead가 남지 않음

절대 하지 말 것

• 내부 task PR에 본 Skill 적용
• merge/반영 전 완료 코멘트 작성
• 작업지시자 승인 없이 PR comment, issue comment, issue close 수행
• 해결 범위가 불명확한 issue close
• 실행하지 않은 검증을 완료 코멘트나 보고서에 기록
• PR/Issue 코멘트 초안 전문을 pr_{N}_report.md에 복제
• 외부 PR 운영 기록 커밋을 로컬에만 남기고 push하지 않음
• Skill, 매뉴얼, 코드, 빌드 설정 변경을 외부 PR 운영 기록 직접 반영 커밋에 섞음
• non-fast-forward 상태에서 강제 push

호출 방법

• Codex: $external-pr-complete PR #N 완료 처리
• Claude Code: /external-pr-complete

외부 기여자 PR 검토

트리거

• 명시 호출만: 작업지시자가 "PR #N 리뷰" 또는 "외부 PR 검토"를 명시 지시한 경우
• 본 SKILL을 직접 호출한 경우

사전 조건

• 검토 대상 PR이 외부 기여자 fork에서 본 저장소 devel(또는 합의된 base)로 열린 상태
• 내부 타스크 PR(publish/task{N})에는 본 SKILL 사용 금지 — 내부 타스크는 일반 단계 절차로 검토
• gh CLI 인증

절차

1. 초기 triage 메타 수집

   gh pr view {N} --json number,title,state,author,baseRefName,headRefName,headRepository,isCrossRepository,assignees,labels,milestone,reviewRequests,body,files,url
   

   • base/head, fork 여부, 작성자, 현재 reviewer request/assignee/label/milestone, 연결 이슈 후보, 변경 파일 목록만 확인한다.
   • 연결 이슈가 있으면 이슈의 label/milestone을 추가 조회한다.

     gh issue view {ISSUE} --json number,title,state,labels,milestone,assignees,url
     

   • 작성자의 첫 외부 기여 여부는 최근/전체 PR에서 작성자 기존 기여와 merge 이력을 확인해 판단한다.
2. Review 시작 triage gate
   • 현재 상태와 권장 triage 값을 작업지시자에게 먼저 응답으로 안내한다.
     • reviewer: 작업지시자/maintainer가 지정한 reviewer
     • assignee: 작성자 또는 담당 maintainer 중 프로젝트 운영 기준에 맞는 사람
     • label: 변경 성격 기준 (documentation, bug, enhancement, area:* 등)
     • milestone: 연결 이슈 milestone 우선. 없거나 애매하면 작업지시자 확인
   • 작업지시자에게 다음 중 하나를 명시 선택하게 하고 여기서 멈춘다.
     • triage 적용 후 리뷰 진행
     • triage 적용 없이 리뷰 진행
     • triage 값 조정
   • 같은 메시지에서 작업지시자가 triage 값과 리뷰 진행을 명시 승인한 경우에만 다음 단계로 이어간다.
   • 승인 전에는 GitHub PR 상태 수정, review 문서 작성, 본격 diff 검토를 하지 않는다.
3. 승인된 triage 적용
   • 작업지시자가 triage 적용을 승인한 경우 필요한 항목만 실행한다.

     gh pr edit {N} --add-reviewer {login}
     gh pr edit {N} --add-assignee {login}
     gh pr edit {N} --add-label "{label}"
     gh pr edit {N} --milestone "{milestone}"
     

   • 권한 문제로 reviewer/assignee/label/milestone 적용이 실패하면 실패 항목을 기록하고, 리뷰 진행 여부를 작업지시자에게 확인한다.
4. 본 리뷰 메타와 diff 수집

   gh pr view {N} --json number,title,state,author,baseRefName,headRefName,headRepository,isCrossRepository,mergeable,mergeStateStatus,reviewDecision,assignees,labels,milestone,reviewRequests,body,comments,reviews,commits,files
   gh pr diff {N} | head -200
   gh pr checks {N}
   

   • 이슈 연결, base/head, fork 여부, mergeable, CI 상태, reviewer/assignee/label/milestone, 기존 코멘트/리뷰를 모두 확인한다.
5. 검토 문서 작성: mydocs/pr/pr_{N}_review.md
   • 표준 섹션:
     • PR 정보 (번호, 작성자, base/head, 연결 이슈)
     • Review 시작 triage (초기 상태, 권장값, 작업지시자 선택, 적용 결과)
     • 변경 요약
     • 영향 범위와 호환성 (FFI, build, 문서, Quick Look/Thumbnail, core pin)
     • 코드/문서 점검 결과
     • 기여자 피드백 판단
       • 잘 된 점과 유지할 방향
       • 기여자에게 요청할 변경
       • 내부 후속 Issue/타스크로 분리할 항목
       • 이 PR 범위에 포함하지 않을 항목
     • 검증 계획 (필요한 추가 검증)
     • 권고 (merge / cherry-pick 통합 / 수정 요청 / 보류 / 닫기)
     • merge 후 완료 처리 handoff 필요 여부
     • 작업지시자 승인 요청
   • PR/Issue 코멘트 초안 전문은 review 문서에 쓰지 않는다. 문서에는 피드백 필요 여부와 요지만 기록한다.
6. 필요 시 수정·검증 계획 문서 작성: mydocs/pr/pr_{N}_review_impl.md
   • 본 저장소에서 추가 검증을 직접 수행할 때 사용한다.
   • 작성 후 작업지시자 승인 요청을 남긴다.
7. 검증 수행 (해당하는 경우만)
   • 빌드/렌더 smoke test 등은 변경 유형에 따라 build_run_guide.md와 swift_macos_code_rules_guide.md 정책을 적용한다.
   • 자기검증만 있는 저장/렌더/호환성 변경은 실제 origin 샘플, 앱 smoke, 시각 비교, 또는 설치본 기준 검증 필요 여부를 따로 판단한다.
8. 기여자 공개 피드백 초안 정리 (응답 전용)
   • 수정 요청, 보류, 닫기, 분리 재제출 권고라면 작업지시자가 GitHub에 직접 등록할 코멘트 초안을 최종 응답에 제시한다.
   • merge 가능 권고라면 완료 코멘트 초안을 만들지 않는다. merge/cherry-pick 후 external-pr-complete에서 처리한다.
   • 첫 기여자라면 환영/감사를 포함하고, 칭찬은 실제 PR에서 확인한 구체적 기여 사실에 붙인다.
   • 문제 안내는 파일/동작/검증 기대값을 포함해 기여자가 바로 수정할 수 있게 쓴다.
   • GitHub PR/Issue 참조 표기는 아래 "GitHub 참조 표기 규칙"을 따른다.
   • 내부 후속 수정은 PR 안에서 몰래 반영하지 않는다. 별도 Issue/내부 타스크 후보와 PR 코멘트 문구를 응답에 분리해 제시하고, 생성/수정은 작업지시자 승인 후에만 진행한다.
9. 작업지시자 승인 후 GitHub review/comment 등록 (필요 시)

   REVIEW_BODY=/tmp/pr_{N}_review_body.md
   # 승인된 공개 review/comment 본문을 "$REVIEW_BODY"에 작성한다.
   scripts/validate-github-body.sh "$REVIEW_BODY"
   
   # merge 권고를 실제 GitHub review로 남길 때
   gh pr review {N} --approve --body-file "$REVIEW_BODY"
   
   # 승인 없이 의견만 남길 때
   gh pr review {N} --comment --body-file "$REVIEW_BODY"
   
   # 수정 요청일 때
   gh pr review {N} --request-changes --body-file "$REVIEW_BODY"
   

   • review request가 남아 있는 PR은 단순 PR comment보다 gh pr review --body-file로 실제 review를 등록해야 알림과 검토 상태가 정리된다.
   • GitHub 공개 review/comment 본문은 inline --body로 넣지 않고 --body-file과 scripts/validate-github-body.sh를 사용한다.
   • 이 단계는 작업지시자가 공개 등록을 승인한 경우에만 수행한다.
10. 검토 완료 응답

• triage 선택/적용 결과, 차단 이슈, 검증 결과, 최종 권고, 작업지시자 승인 요청을 요약한다.
• merge 가능 권고일 때는 PR 완료 코멘트 초안을 작성하지 않는다.
• 공개 코멘트 초안이 필요한 경우 review 문서 경로가 아니라 응답 본문에만 제공한다.
• 작업지시자가 merge/cherry-pick/close를 완료하거나 완료 처리를 지시하면 external-pr-complete Skill을 호출하라고 안내한다.

11. 단일 또는 단계별 커밋 (외부 PR 검토는 내부 단계 형식 강제 아님)

git commit -m "PR #{N} 검토: {요약}"

판단 기준

• PR base가 정책과 다르면 devel 또는 합의된 대상 브랜치로 재정렬을 요청한다. 변경이 작고 작업지시자가 승인한 경우에만 maintainer가 대상 브랜치에 직접 반영할 수 있다.
• reviewer request, assignee, label, milestone은 검토 시작 triage로 제안하고, 작업지시자 수락 전에는 본 리뷰로 넘어가지 않는다.
• 작업지시자가 triage 적용 없이 리뷰 진행을 명시하면 GitHub 상태를 바꾸지 않고 본 리뷰를 진행한다.
• label/milestone은 연결 이슈를 우선 따른다. 연결 이슈가 없거나 PR 범위가 이슈와 다르면 임의 지정하지 말고 확인한다.
• 작성자 PR을 그대로 merge할지 cherry-pick할지는 작업지시자 결정이다. merge/cherry-pick 후 공개 완료 코멘트, issue comment/close, pr_{N}_report.md, archives 이동은 external-pr-complete Skill에서 처리한다.
• 외부 PR 검토 중 발견한 문제는 기여자가 이 PR에서 고쳐야 할 항목과 메인테이너가 별도 Issue/내부 타스크로 처리할 항목으로 분리한다.
• 외부 PR이 내부 후속 수정을 요구하면 같은 PR에서 몰래 고치지 말고 별도 GitHub Issue 또는 내부 타스크로 분리한다. 기여자에게는 이 PR의 merge 조건인지, 별도 후속으로 추적할 항목인지 구체적으로 안내한다.
• PR 범위를 넘는 내부 보완은 기여자에게 요구하지 않는다. 다만 현재 PR의 안정성·호환성·검증을 막는 항목이면 차단 이유와 필요한 최소 수정 범위를 명확히 적는다.
• Finder/Quick Look/Thumbnail 변경은 Debug 빌드만으로 승인하지 않는다. 설치본 또는 표준 smoke helper 기준의 registration hygiene를 확인한다.
• Sources/RhwpCoreBridge에 AppKit/UIKit 직접 의존, Alhangeul.xcodeproj 직접 수정, floating core ref, 승인 없는 릴리스/서명/공증 변경은 차단 이슈로 기록한다.

GitHub 참조 표기 규칙

• 리뷰 코멘트 초안과 내부 후속 Issue/타스크 안내 문구에서 GitHub PR/Issue 참조 토큰을 한글 조사와 붙여 쓰지 않는다.
• #328으로, #132를, PR #328은처럼 쓰지 말고 #328 반영으로, #132 이슈를, PR #328 반영은처럼 참조 토큰 뒤를 공백, 문장 부호, 또는 별도 명사로 분리한다.
• 여러 대상을 함께 적을 때는 PR #328 및 Issue #132처럼 각 참조 토큰을 독립적으로 둔다.

리뷰 코멘트 초안 원칙

• 초안은 최종 응답에만 작성한다. mydocs/pr/pr_{N}_review.md에는 초안 전문을 넣지 않는다.
• 첫 기여자라면 첫 문단에 환영과 감사를 둔다. "좋은 PR" 같은 포괄 칭찬보다 문제 재현, 작은 범위, 테스트 보강, 문서 정리, maintainer 피드백 반영처럼 확인 가능한 사실을 칭찬한다.
• 개선 안내는 "무엇을", "어디서", "어떤 검증으로" 고치면 되는지 적는다. 단순히 "수정 필요"라고 쓰지 않는다.
• 내부 후속 분리 항목은 기여자의 책임처럼 쓰지 않는다. PR 코멘트에는 "이 PR에서는 요청하지 않고 별도 Issue/내부 타스크로 추적"한다고 명확히 적고, 필요하면 내부 이슈/타스크 초안은 별도 섹션으로 제시한다.
• 닫기 또는 분리 재제출 권고는 기여를 부정하지 않는 문장으로 시작하고, 다시 제출 가능한 최소 범위와 base branch를 함께 안내한다.

수정 요청 코멘트 템플릿

검토 감사합니다. {첫 기여자라면 환영 문장} {구체적으로 좋았던 점}

merge 판단 전에 아래 항목 보강이 필요합니다.

- {파일/동작}: {필요한 수정}. 확인 기준: `{검증 명령 또는 수동 확인}`
- {파일/동작}: {필요한 수정}. 확인 기준: `{검증 명령 또는 수동 확인}`

{PR 범위를 넘는 내부 후속 항목이 있으면: "{항목}은 이 PR에서 요청하지 않고 별도 Issue/내부 타스크로 추적하겠습니다."}

검증

• mydocs/pr/pr_{N}_review.md 표준 섹션 충족
• review 시작 triage의 초기 상태, 권장 값, 작업지시자 선택, 적용 결과가 기록됨
• review 문서에 PR/Issue 완료 코멘트 초안 전문이 포함되지 않음
• 기여자 피드백 판단에 잘 된 점, 요청 변경, 내부 후속 분리 항목, PR 범위 제외 항목이 구분됨
• 권고 결정이 명시됨 (merge / cherry-pick 통합 / 수정 요청 / 보류 / 닫기 중 하나)
• GitHub 공개 review/comment를 등록했다면 body file이 scripts/validate-github-body.sh를 통과함
• merge 가능 권고라면 후속 external-pr-complete 호출 필요성이 명시됨

절대 하지 말 것

• 내부 타스크 PR(publish/task{N})에 본 SKILL 적용
• 외부 PR을 작업지시자 승인 없이 merge 또는 close
• 작업지시자 승인 없이 reviewer request, assignee, label, milestone 수정
• triage gate 수락 없이 본격 diff 검토, 검토 문서 작성, 검증 수행
• 작업지시자 승인 없이 GitHub review/comment 등록
• GitHub 공개 review/comment 본문을 inline --body로 등록
• merge 가능 판단만으로 PR/Issue 완료 코멘트 작성 또는 issue close
• 내부 후속 수정을 외부 PR 안에서 몰래 처리하거나 PR 범위를 넓혀 기여자에게 떠넘김
• 작업지시자 승인 없이 내부 후속 Issue/타스크 생성
• 작업지시자 승인, attribution 보존, 검토/보고서 기록 없이 외부 기여자 코드를 cherry-pick
• 내부 단계 절차(_stage{N}.md, _report.md) 형식을 외부 PR 문서에 강제 적용

호출 방법

• Codex: $external-pr-review 또는 /skills 메뉴
• Claude Code: /external-pr-review

PR merge 후 부산물 정리

트리거

• 명시 호출만: 작업지시자가 "merge 후 정리", "타스크 정리"를 명시 지시한 경우
• 본 SKILL을 직접 호출한 경우

사전 조건

• 대상 PR이 GitHub에서 실제 merged 상태 (gh pr view {번호} --json state,mergeCommit)
• 작업지시자의 이슈 close 승인 (또는 PR 본문에 closes #N 명시되어 자동 close된 상태)

절차

1. PR과 이슈 상태 확인

   gh pr view {번호} --json state,mergedAt,mergeCommit,headRefName
   gh issue view {N} --json state
   

   • PR state == MERGED 아니면 즉시 중단하고 작업지시자 보고
2. 이슈 close (자동 close 안 된 경우만)

   gh issue close {N}
   

3. 대상 통합 브랜치 최신화

   git fetch origin --prune
   BASE_BRANCH=$(gh pr view {번호} --json baseRefName --jq .baseRefName)
   git checkout "$BASE_BRANCH"
   git pull --ff-only
   

   • git pull --ff-only가 실패하면 git status --short --branch와 git log --oneline origin/$BASE_BRANCH..$BASE_BRANCH를 확인한다.
   • local-only 커밋이 외부 PR 운영 기록(PR #N 검토, PR #N 완료 처리)이고 변경 파일이 mydocs/pr/**에만 있으면, 작업지시자 승인 후 git rebase origin/$BASE_BRANCH로 최신화하고 git push origin "$BASE_BRANCH"로 직접 반영한다.
   • Skill, 매뉴얼, 코드, 빌드 설정, 앱 동작 변경이 섞여 있으면 직접 push하지 말고 별도 Issue/브랜치/PR 절차로 분리한다.
   • local-only 커밋 성격이 불명확하면 reset/rebase/force push를 하지 말고 작업지시자에게 보고한다.
4. 원격 publish 브랜치 삭제 (이미 PR merge 시 --delete-branch로 삭제된 경우 skip)

   git push origin --delete publish/task{N} 2>&1 || echo "이미 삭제됨"
   

5. 분리 worktree 사용했다면 제거

   git worktree remove ../{repo}-task{N}
   git worktree prune
   

6. 로컬 작업 브랜치 삭제 (재사용 가능성 없을 때만)

   git branch -d local/task{N}
   # 강제 삭제는 작업지시자 명시 승인 후에만: git branch -D local/task{N}
   

7. 오늘할일 최종 정리: mydocs/orders/{yyyymmdd}.md의 #{N} 행이 완료 + 시각 기록되어 있는지 재확인
8. 결과 보고: 정리된 항목 목록을 작업지시자에게 짧게 회신

검증

• gh pr view {번호} state == MERGED 확인
• git branch -vv | grep local/task{N} 출력 없음 (삭제된 경우)
• git ls-remote origin publish/task{N} 빈 출력 (원격 삭제 확인)
• git worktree list 출력에 정리 대상 worktree 미존재
• git branch --show-current가 대상 PR의 baseRefName
• 외부 PR 운영 기록을 직접 반영했다면 git status --short --branch에 대상 branch의 local-only ahead가 남지 않음

절대 하지 말 것

• PR이 merged 상태가 아닌데 이슈 close
• 작업지시자 다른 task 브랜치(local/task{다른번호})나 메인 worktree 삭제
• git branch -D 강제 삭제 무단 사용 (병합 안 된 커밋이 있을 때 손실 위험)
• 외부 PR 운영 기록이 아닌 local-only 커밋을 cleanup 과정에서 직접 push
• non-fast-forward 상태에서 강제 push
• 다른 작업자의 stash 삭제

호출 방법

• Codex: $pr-merge-cleanup 또는 /skills 메뉴
• Claude Code: /pr-merge-cleanup

하이퍼-워터폴 최종 보고와 PR 게시

트리거

• 명시 호출만: 작업지시자가 "최종 보고서 작성", "PR 준비"를 명시 지시한 경우
• 본 SKILL을 직접 호출한 경우

사전 조건

• 구현 계획서의 모든 단계 종료, 각 단계 보고서 커밋 완료
• 통합 검증(전체 수용 기준) 통과 확인
• local/task{N}에 commit 안 된 변경 없음 또는 본 절차에서 함께 커밋할 것만 남아 있음

절차

1. 통합 검증: 구현 계획서의 "수용 기준" 또는 마지막 단계 "검증" 섹션 명령 실행
2. 최종 보고서 작성: mydocs/report/task_m{milestone}_{N}_report.md
   • 표준 섹션:
     • 작업 요약 (이슈 링크, 마일스톤, 단계 수)
     • 변경 파일 목록과 영향 범위
       • 반드시 Markdown table로 작성한다.
       • 기본 컬럼은 파일 | 내용으로 한다.
       • 단순 파일 목록만 나열하지 않는다.
     • 변경 전·후 정량 비교 (라인 수, 토큰, 검증 통과 등 적용 시)
     • 검증 결과 (수용 기준별 OK/MISS)
     • 잔여 위험과 후속 작업
     • 작업지시자 승인 요청
3. 오늘할일 갱신: mydocs/orders/{yyyymmdd}.md의 #{N} 행
   • 상태 완료로 변경, 비고에 완료: HH:mm 기록
4. 변경 점검

   git status --short
   git diff --check
   BASE_BRANCH=devel # Swift native viewer/editor 작업이면 native-viewer-editor
   git log --oneline "$BASE_BRANCH"..local/task{N}
   

5. 최종 커밋 (Stage 마지막 + 최종 보고서를 묶을 수도, 보고서만 단일 커밋도 가능)

   git add mydocs/report/task_m{milestone}_{N}_report.md mydocs/orders/{yyyymmdd}.md
   git commit -m "Task #{N} Stage {마지막} + 최종 보고서: {요약}"
   # 또는
   git commit -m "Task #{N}: 최종 보고서 작성과 오늘할일 완료 처리"
   

6. 원격 게시 브랜치 push

   git push origin local/task{N}:publish/task{N}
   

7. 통합 브랜치 대상 Open PR 생성

   BASE_BRANCH=devel # Swift native viewer/editor 작업이면 native-viewer-editor
   HEAD_SHA=$(git rev-parse HEAD)
   PR_BODY=/tmp/task{N}-pr-body.md
   # .github/pull_request_template.md를 출발점으로 삼아 최종 보고서와 단계 보고서 기준으로 "$PR_BODY" 작성
   scripts/validate-github-body.sh "$PR_BODY"
   gh pr create --base "$BASE_BRANCH" --head publish/task{N} \
     --title "Task #{N}: {제목}" \
     --body-file "$PR_BODY"
   

   • PR 본문은 최대 4개 요약 bullet, Stage별 1줄 요약, 핵심 리뷰 포인트, 검증 결과, 관련 이슈, 후속 이슈 제안, 남은 리스크를 포함
   • Stage 제목은 단계 보고서 URL로, 옆의 짧은 commit SHA는 commit URL로 링크
   • 작업 문서는 HEAD_SHA 기준 https://github.com/postmelee/alhangeul-macos/blob/{HEAD_SHA}/mydocs/... URL로 연결
   • 링크 표시는 raw URL이 아니라 [파일명](URL) 형식으로 작성
   • 상대 링크(mydocs/...)나 blob/publish/task{N}/... 링크는 사용하지 않음
   • 시각적 변경사항이 있을 때만 Before/After 표를 유지
   • 관련 이슈에는 대상 타스크가 아니라 선행, 후속, Epic, upstream, 참고 PR/issue만 작성
   • GitHub 공개 PR 본문은 inline --body로 넣지 않고 --body-file과 scripts/validate-github-body.sh를 사용
8. 작업지시자에게 PR URL 전달과 리뷰·merge 승인 요청

검증

• 모든 단계 보고서 + 최종 보고서 존재
• git status --short 결과 빈 출력
• gh pr view 결과에 draft가 아닌 PR이 정확한 base/head로 등록
• PR 본문 변경 내역의 Stage별 요약이 단계 보고서 링크와 짧은 commit SHA 링크를 함께 사용
• PR 본문 변경 내역의 작업 문서 항목이 commit SHA 고정 URL과 [파일명](URL) 표시 형식을 사용
• PR 본문 작업 문서 항목에 raw GitHub blob URL, 상대 링크, blob/publish/task{N} 링크 없음
• PR 본문에 핵심 리뷰 포인트와 후속 이슈 제안을 필요한 경우 유지하고, 해당 없으면 삭제하거나 없음으로 정리
• PR 본문에 실행하지 않은 검증 체크리스트가 남아 있지 않음
• PR 본문 파일이 scripts/validate-github-body.sh를 통과
• 오늘할일 #{N} 상태 완료 + 완료: HH:mm

절대 하지 말 것

• 통합 검증 실패 상태에서 PR 생성
• local/task{N} 브랜치를 원격에 직접 push (반드시 publish/task{N}로 명명)
• squash merge 강제 옵션 사용 (단계 커밋 의미 보존)
• 작업지시자 명시 지시 없이 Draft PR로 생성하거나 self-merge

호출 방법

• Codex: $task-final-report 또는 /skills 메뉴
• Claude Code: /task-final-report

하이퍼-워터폴 이슈 등록

트리거

• 명시 호출만: 작업지시자가 "이 작업 이슈 등록", "새 타스크 생성", "이슈부터 만들어줘"처럼 GitHub Issue 생성을 명시한 경우
• 작업지시자가 본 SKILL을 직접 호출한 경우

사전 조건

• 아직 이슈 번호가 없는 작업
• 작업 목적, 배경, 범위가 최소한 초안 수준으로 정리됨
• 현재 사용자 자격 증명으로 gh CLI 인증 완료
• 이슈 생성 전 제목, 본문, milestone, label 초안을 작업지시자에게 확인받을 수 있음

절차

1. 중복 이슈 확인

   gh issue list --repo postmelee/alhangeul-macos --state all \
     --search "{작업 키워드}" \
     --limit 20 \
     --json number,title,state,milestone,labels,url
   

   • 실질적으로 같은 열린 이슈가 있으면 새 이슈를 만들지 말고 기존 이슈 사용 여부를 확인한다.
   • 닫힌 이슈가 같은 주제를 다뤘다면 새 이슈 본문 참고 항목에 링크한다.
2. 열린 milestone 목록 확인

   gh api repos/postmelee/alhangeul-macos/milestones \
     --jq '.[] | {number,title,state,description,open_issues,closed_issues}'
   

   • 조회 결과의 title, state, description을 기준으로 판단한다.
   • 기억하고 있는 과거 milestone 목록이나 버전 매핑을 기준으로 단정하지 않는다.
3. 기존 label 목록 확인

   gh api repos/postmelee/alhangeul-macos/labels --paginate \
     --jq '.[] | {name,description,color}'
   

   • 조회 결과의 name, description을 기준으로 판단한다.
   • 기억하고 있는 과거 label 목록을 기준으로 단정하지 않는다.
4. milestone 후보 선택
   • 열린 milestone만 후보로 사용한다.
   • 작업 목적, 범위, 대상 컴포넌트, 릴리스 단계가 조회된 milestone의 title/description과 가장 잘 맞는지 비교한다.
   • 후보가 명확하면 milestone 제목과 선택 이유를 기록한다.
   • 후보가 2개 이상이면 2~3개 후보와 각각의 이유를 작업지시자에게 제시하고 확인받는다.
   • 적합한 열린 milestone이 없거나 설명이 부족하면 임의 선택하지 말고 작업지시자에게 확인한다.
5. label 후보 선택
   • 조회된 기존 label만 후보로 사용한다.
   • 작업 성격이 label의 name/description과 명확히 대응할 때만 선택한다.
   • label은 기본적으로 type label 1개 + area label 1~2개 + kind/status label 0~1개로 제한한다.
   • type label은 bug, documentation, enhancement, duplicate, question 등 작업 성격을 나타내는 label 중 1개를 우선 고른다.
   • area:* label은 영향을 받는 모든 영역이 아니라 주 작업 소유 영역 기준으로 고른다.
   • kind:* label은 kind:architecture, kind:automation, kind:regression, kind:verification, kind:follow-up처럼 처리 방식이나 맥락을 실제로 구분할 때만 붙인다.
   • 일반 이슈는 2~4개 label을 권장한다.
   • 5개 이상 label이 필요하면 이슈 초안에 예외 사유를 적고 작업지시자 확인을 받는다.
   • 후보가 명확하면 label 이름과 선택 이유를 기록한다.
   • 적합한 label이 없거나 애매하면 label 없이 생성하거나 작업지시자에게 확인한다.
   • 새 label은 만들지 않는다.
6. 이슈 초안 작성
   • 제목: 작업 단위가 드러나는 한 문장
   • 본문 권장 섹션:
     • 배경
     • 목표
     • 범위
     • 제외
     • 참고
   • milestone: live 조회 결과에서 고른 열린 milestone 1개와 선택 이유
   • label: live 조회 결과에서 고른 기존 label 0개 이상과 선택 이유
   • label 선택 이유는 type/area/kind 기준으로 나누어 적고, 5개 이상이면 예외 사유를 별도로 적는다.
7. 이슈 생성 전 승인 요청
   • 작업지시자에게 제목, 본문, milestone, label 초안과 선택 이유를 보여준다.
   • 작업지시자가 같은 스레드에서 생성 승인을 명시하기 전에는 gh issue create를 실행하지 않는다.
8. 승인 후 이슈 생성

   ISSUE_BODY=/tmp/task-register-issue-body.md
   # 승인된 이슈 본문을 "$ISSUE_BODY"에 작성한다.
   scripts/validate-github-body.sh "$ISSUE_BODY"
   gh issue create --repo postmelee/alhangeul-macos \
     --title "{제목}" \
     --body-file "$ISSUE_BODY" \
     --milestone "{milestone}" \
     --label "{label}"
   

   • label이 여러 개면 --label documentation --label enhancement처럼 반복한다.
   • label을 쓰지 않기로 했으면 --label 옵션을 생략한다.
   • GitHub 공개 본문은 inline --body로 넣지 않고 --body-file과 scripts/validate-github-body.sh를 사용한다.
9. 생성 결과 확인

   gh issue view {N} --repo postmelee/alhangeul-macos \
     --json number,title,state,milestone,labels,url
   

10. 작업지시자에게 생성된 이슈 번호와 URL을 보고하고 task-start 진입 승인 요청

검증

• 생성된 이슈가 OPEN 상태여야 한다.
• milestone이 비어 있지 않고 live 조회 결과에 있던 열린 milestone이어야 한다.
• label은 초안에서 승인된 기존 label만 붙어 있어야 한다.
• 일반 이슈 label은 2~4개 권장 범위인지 확인한다.
• 5개 이상 label이면 승인된 예외 사유가 생성 결과 보고에 포함되어야 한다.
• area:* label은 주 작업 소유 영역 기준으로 선택되어야 한다.
• 생성 결과 보고에 issue number, URL, milestone, label, 선택 이유가 포함되어야 한다.
• 이슈 본문 파일이 scripts/validate-github-body.sh를 통과해야 한다.

절대 하지 말 것

• 작업지시자 승인 없이 gh issue create 실행
• GitHub 공개 이슈 본문을 inline --body로 등록
• 새 milestone 또는 새 label 생성
• 닫힌 milestone을 임의로 사용
• 이슈 생성 후 승인 없이 task-start까지 이어서 실행
• 이 Skill 안에서 브랜치 생성, 오늘할일 갱신, 수행계획서 작성

호출 방법

• Codex: $task-register 또는 /skills 메뉴에서 task-register 선택
• Claude Code: /task-register

하이퍼-워터폴 단계 종료 보고

트리거

• 명시 호출만: 작업지시자가 "Stage {N} 마무리", "단계 보고서 작성"을 명시 지시한 경우
• 본 SKILL을 직접 호출한 경우

사전 조건

• 구현 계획서(task_m{milestone}_{N}_impl.md)가 존재하고 작업지시자 승인됨
• 현재 단계의 작업 항목이 모두 코드/문서에 반영됨
• 작업 브랜치는 local/task{N}

절차

1. 단계별 검증 명령 실행 (구현 계획서의 해당 단계 "검증" 섹션 그대로)
   • 결과를 보고서에 인용할 수 있도록 출력 보존
2. 단계 보고서 작성: mydocs/working/task_m{milestone}_{N}_stage{S}.md
   • 표준 섹션:
     • 단계 목적
     • 산출물 (파일 목록 + 라인 수 또는 요약)
     • 본문 변경 정도 / 본문 무손실 여부 (해당 시)
     • 검증 결과 (위 1번 출력 인용)
     • 잔여 위험
     • 다음 단계 영향
     • 승인 요청 (다음 단계 진입 또는 PR 단계)
3. 변경 점검

   git status --short
   git diff --check
   

4. 단계 소스 + 보고서 묶음 커밋

   git add {단계 산출 파일들} mydocs/working/task_m{milestone}_{N}_stage{S}.md
   git commit -m "Task #{N} Stage {S}: {핵심 내용 요약}"
   

   • 하위 단계: Task #{N} [Stage {S.M}]: 내용
   • 최종 단계 + 최종 보고서 묶음: Task #{N} Stage {S} + 최종 보고서: 내용 (이 경우 별도 SKILL task-final-report로 처리 권장)
5. 작업지시자에게 단계 보고서 검토와 다음 단계 진입 승인 요청

검증

• git log --oneline -1이 단계 커밋 메시지 표준 형식 충족
• mydocs/working/task_m{milestone}_{N}_stage{S}.md 존재
• 단계별 검증 명령이 실패 없이 통과 (실패 시 단계 미완료로 처리하고 보고서 작성 보류)

절대 하지 말 것

• 검증 실패 상태로 보고서 작성·커밋
• 단계 산출물과 보고서를 분리해 별도 커밋 (한 단계는 한 커밋 원칙)
• 작업지시자 승인 없이 다음 단계 진입

호출 방법

• Codex: $task-stage-report 또는 /skills 메뉴
• Claude Code: /task-stage-report

하이퍼-워터폴 타스크 시작

트리거

• 명시 호출만: 작업지시자가 "이슈 #N 시작", "타스크 #N 진행"처럼 명시 지시한 경우
• 작업지시자가 본 SKILL을 직접 호출한 경우

사전 조건

• 작업지시자 승인된 이슈 번호와 마일스톤이 존재
• 작업 대상 저장소 working tree clean (또는 분리된 worktree 사용 결정)
• 현재 사용자 자격 증명으로 gh CLI 인증 완료

절차

1. 이슈 정보 확인

   gh issue view {N} --json number,title,milestone,state,body
   

2. 기준 통합 브랜치 결정 후 최신화
   • 첫 공개 배포, WKWebView-backed viewer/editor, Finder/Quick Look, PDF/공유/저장, Spotlight/mdimporter, 변환, 배포, 문서는 devel
   • Swift native viewer/editor 작업은 native-viewer-editor
   • 작업지시자가 명시한 base가 있으면 그 지시를 우선

   BASE_BRANCH=devel # Swift native viewer/editor 작업이면 native-viewer-editor
   git fetch origin
   git checkout "$BASE_BRANCH"
   git pull --ff-only
   

3. 작업 브랜치 생성. 다른 작업자가 메인 worktree를 점유 중이면 분리 worktree 사용:

   # 단일 worktree
   git checkout -b local/task{N}
   
   # 분리 worktree (권장: 다른 에이전트 비간섭)
   git worktree add ../{repo}-task{N} -b local/task{N} origin/"$BASE_BRANCH"
   

4. 오늘할일 갱신: mydocs/orders/{yyyymmdd}.md에 행 추가
   • 형식: | #{N} | {타스크 제목} | 진행중 | M{milestone}, 수행계획서 작성 후 승인 대기 |
   • 적절한 마일스톤 섹션에 배치
   • Release Operations milestone은 M900 — Release Operations 섹션을 사용
   • 등록된 운영 milestone 문서 코드가 없는 운영 작업은 "공통 — 운영 작업"에 임시 배치하고, 문서 코드 확정 후 옮김
5. 수행계획서 템플릿 생성: mydocs/plans/task_m{milestone}_{N}.md
   • 섹션: 목적 / 배경 / 범위(포함·제외) / 설계 방향 / 예상 변경 파일 / 잠정 단계(3~6단계) / 검증 계획 / 리스크 / 승인 요청 사항
6. 변경 검증

   git status --short
   git diff --check
   

7. 단일 커밋

   git add mydocs/plans/task_m{milestone}_{N}.md mydocs/orders/{yyyymmdd}.md
   git commit -m "Task #{N}: 수행 계획서 작성과 오늘할일 갱신"
   

8. 작업지시자에게 수행계획서 승인 요청

검증

• git log --oneline -1이 Task #{N}: 수행 계획서 작성과 오늘할일 갱신을 보여야 한다
• mydocs/orders/{yyyymmdd}.md에 #{N} 행 존재
• mydocs/plans/task_m{milestone}_{N}.md 9개 표준 섹션 모두 채워짐

절대 하지 말 것

• 수행계획서 승인 전 구현 계획서 작성
• 수행계획서 승인 전 코드/매뉴얼 변경
• 다른 작업자의 미커밋 변경 또는 다른 task 브랜치 working tree 건드리기

호출 방법

• Codex: $task-start 또는 /skills 메뉴에서 task-start 선택
• Claude Code: /task-start