create-pr

name	create-pr
argument-hint	[update]
description	Create structured PR. Default: create new PR. Args: update (existing PR body). Trigger: 'PR 만들어줘', 'PR 생성', 'PR 올려', 'create PR', 'PR 업데이트', 'Human Test'. NOT for DA (use run-da). NOT for PR 코멘트 (use review-pr-feedback). NOT for 머지 후 종결 절차 (use finish-pr).

상세 PR 작성

스킬 호출 인자로 update를 수신하면 기존 PR 본문을 업데이트하고, 인자가 비어있거나 다른 값이면 새 PR을 생성한다.

빠른 참조

항목	위치
7섹션 PR 본문 템플릿 상세	references/pr-template.md

필수 7섹션 템플릿

PR 본문은 반드시 다음 7개 섹션을 포함한다.

#	섹션	역할
1	Summary	핵심 변경 1-3 bullet + Closes #N
2	기존 문제/배경	Pain point — 왜 이 변경이 필요한지
3	CIR (Change Intent Record)	발견 경위 + 설계 의도 + 대안 검토 이력. 검토 라운드/finding ID/partial hash chain 포함 금지 (변경 의도는 자연어로)
4	ADR (Architecture Decision Record)	대안 비교 테이블 (대안/설명/장점/단점/결정)
5	구현 상세	변경 파일 테이블 + 핵심 코드 스니펫
6	참고 레퍼런스	관련 PR/이슈/외부 링크 (안정 식별자: PR 번호, 이슈 번호, 또는 머지된 SHA — partial hash chain 금지)
7	Human Test Plan	단계별 기대동작 + 실패 시 진단 가이드

각 섹션의 작성 규칙, 예시, 흔한 실수는 references/pr-template.md 참조.

PR 전 결정

PR을 생성하기 전에, 작업 결과의 처리 방향을 결정한다:

선택지	조건	행동
PR 생성	리뷰가 필요한 변경	이 스킬의 절차를 진행
직접 merge	사용자가 명시적으로 승인한 단순 변경	main에 현재 브랜치를 git merge 후 종료
보류 (keep)	추가 작업이 필요하거나 다른 브랜치와 조율 필요	사용자에게 보고 후 종료
폐기 (discard)	접근 방식이 잘못되었거나 불필요해짐	사용자 확인 후 브랜치 삭제

판단이 어려우면 PR 생성을 기본으로 선택한다.

절차

새 PR 생성 (기본)

수신한 인자가 비어있거나 update가 아닌 경우 새 PR을 생성한다.

1. 변경 분석: git diff main...HEAD와 커밋 히스토리(git log main..HEAD --oneline)를 분석하여 변경 범위를 파악한다.

2. 연관 이슈 탐색: 커밋 메시지, 브랜치명, 변경 내용에서 이슈 번호를 추출한다. 관련 이슈가 있으면 Summary에 Closes #N을 포함한다.

3. CIR 수집: 코드 인라인 주석(# CIR:, # === Change Intent Record ===)과 커밋 메시지에서 의사결정 이력을 추출한다. 현재 대화 컨텍스트에서도 방향 전환/대안 거부 이력을 수집한다. 워크트리에 implementation-notes.md가 있으면 아래 흡수 계약을 적용한다.

   흡수 계약 (finding-unknowns 방법론 — 이 정의가 정본이며 update 경로도 동일 적용):

   • provenance 확인: 파일 1행이 owner header <!-- owner: finding-unknowns -->이고, git ls-files --error-unmatch -- implementation-notes.md가 실패(=untracked)해야 흡수 대상이다. header가 없거나 tracked 파일이면 방법론 산출물로 단정하지 말고 흡수·삭제 없이 충돌로 보고한다.
   • 흡수 범위: Decisions / Deviations / 새로 발견된 미지 세 섹션 전부를 CIR의 1차 소스로 반영한다.
   • durable marker: 흡수한 PR 본문에는 hidden marker <!-- methodology: finding-unknowns -->를 포함한다 — finish-pr 퀴즈 게이트가 별도 세션에서도 방법론 적용 PR을 판별하는 1차 신호다.
   • 수명: 흡수 완료를 보고하기 전까지 그 파일을 삭제·이동하지 않는다 (수명 규칙 SoT: finding-unknowns 스킬).

4. ADR 테이블 구성: 검토한 대안들을 비교 테이블로 정리한다. 대안이 1개뿐이면 ADR 섹션을 간소화한다.

5. 7섹션 템플릿 작성: references/pr-template.md의 템플릿에 따라 전체 PR 본문을 작성한다. 명시적 시각 증빙 후보가 있으면 using-gh-attach 스킬의 절차를 적용한다 — 처리 결과를 반영한 본문 사본을 아래 6단계의 --body-file로 게시하고(성공한 후보의 첨부는 유지, 실패·skip 후보만 제외), 정본이 정의한 ATTACH_STATUS를 최종 응답에 포함한다.

6. PR 생성: 본문을 임시 파일로 작성한 뒤 gh pr create --title "<제목>" --body-file <파일>로 PR을 생성한다 — 본문을 shell 인자로 싣지 않는다 (multiline 본문의 프로세스 목록/로그 노출 방지, review-pr-feedback의 파일/stdin 전달 규칙과 동일). 제목은 70자 미만, conventional commit 형식을 따른다.

7. 구현 노트 정리: 3단계에서 implementation-notes.md를 흡수한 경우, 다음 세 조건을 모두 확인한 뒤에만 그 파일을 삭제한다 (남겨두면 finish-pr의 워크트리 정리가 dirty로 중단됨) — ① 1행 owner header 일치, ② git ls-files --error-unmatch -- implementation-notes.md 실패(untracked; tracked면 Git 밖 삭제 금지), ③ 생성된 PR 본문에 Decisions·Deviations·새로 발견된 미지 세 섹션 각각과 durable marker가 모두 반영되었는지 확인 (일부 섹션만 반영된 상태로 통과 금지). 하나라도 어긋나거나 PR 생성이 실패하면 파일을 보존하고 중단한다.

기존 PR 업데이트 (update)

수신한 인자가 update인 경우 기존 PR 본문을 보강한다.

1. 현재 PR 확인: gh pr view --json body,title,number로 현재 PR 본문을 가져온다.
2. 누락 섹션 탐지: 7섹션 중 빠진 섹션을 식별한다.
3. 부실 섹션 강화: 있지만 내용이 부실한 섹션(예: Summary만 있고 CIR 없음)을 보강한다. 커밋 히스토리, 코드 변경, 대화 컨텍스트에서 추가 정보를 수집한다. 워크트리에 implementation-notes.md가 있으면 새 PR 생성 절차의 흡수 계약을 그대로 적용한다 (provenance 확인, 세 섹션 전부, durable marker — marker가 본문에 없으면 이때 기록). 기존 user-attachments 링크는 보존하고 재업로드하지 않으며, 명시적으로 새로 제공된 시각 증빙 후보만 using-gh-attach 스킬의 절차를 적용한다 — 처리 결과를 반영한 본문을 4단계의 --body-file 업데이트에 사용하고 ATTACH_STATUS를 최종 응답에 포함한다.
4. 업데이트 적용: 새 본문을 임시 파일로 작성해 gh pr edit <number> --body-file <파일>로 업데이트한다 (본문 shell 인자 전달 금지 — 새 PR 생성 절차와 동일).
5. 구현 노트 정리: implementation-notes.md를 흡수한 경우 새 PR 생성 절차의 구현 노트 정리 단계와 동일하게, 세 조건(owner header · untracked · 세 섹션 각각+marker 반영) 확인 후에만 삭제하고 실패 시 보존한다.

주의사항

• ADR 테이블 표기: 채택한 대안은 ✅, 기각한 대안은 ❌로 표시한다.
• 참고 레퍼런스 식별자: 관련 PR/이슈/외부 링크는 안정 식별자(PR 번호 #N, 이슈 번호 #N, 또는 머지된 commit SHA)를 사용한다. 본인 PR의 mid-flight commit hash 또는 squash 전 partial hash chain은 박제 금지 — squash 후 dangling 위험. "관련 PR 참조" 식의 모호한 레퍼런스도 금지.
• DA 피드백 분리: DA 피드백 루프 결과는 PR 본문이 아닌 별도 코멘트로 분리한다. PR 본문에는 최종 결론만 반영한다.
• CIR 없는 PR: 단순 변경(타이포 수정, 버전 업데이트 등)은 CIR/ADR 섹션을 "해당 없음 — 단순 변경"으로 간소화한다. 무리하게 의사결정 이력을 만들어내지 않는다.
• 제거/되돌림 결정의 근거 보존: 변경이 기존 코드/정책을 제거·되돌리는 것이면, CIR에 "무엇을 왜 제거하며, 그것이 과거에 의도적으로 도입된 것이면 도입 근거·출처(PR#/commit/issue#)"를 명시한다. 비자명한 방어 로직·트레이드오프 선택은 코드 옆 인라인 # CIR: 주석으로 "왜 이렇게 했는지(제거 시 주의)"를 남긴다 — 미래 세션의 의사결정·회귀 조사가 읽을 신호 품질을 높인다 (../run-da/references/decision-regression-audit.md).
• 도구-중립 기술 (Codex / Claude Code / headless 공통): 특정 AI 에이전트 전용 도구명을 본문에 하드코딩하지 않는다. "gh pr create를 실행한다"가 아니라 "PR을 생성한다"처럼 행동 의도로 기술한다. 단, 참조/예시에서의 CLI 명령(gh pr create 등)은 예외로 허용한다.
• PR 본문 박제 금지 항목: 라운드 번호(Round N), DA finding ID(예: Correctness-1, CORR-2), partial commit hash chain, 워크트리 절대경로.
  • 변경 의도(why)는 자연어 설명으로 표현한다. lefthook commit-msg hook은 라운드 번호/DA finding ID/DA 키워드만 warn-only로 감지한다. partial commit hash chain 감지 패턴의 실존 SSOT는 ../../lib/pinning-patterns.sh이며, PR 본문 작성 시에는 본 가이드의 prose 규칙으로 직접 점검한다. 워크트리 절대경로는 본 가이드 자체에서 자연어 설명·repo-relative 경로로 대체하여 점검한다. PR 본문도 동일 정책을 따른다.

참조 자료

• references/pr-template.md — 7섹션 PR 본문 마크다운 템플릿 + 섹션별 작성 규칙/예시/흔한 실수