하이퍼-워터폴 이슈 등록

트리거

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

사전 조건

• 아직 이슈 번호가 없는 작업
• 작업 목적, 배경, 범위가 최소한 초안 수준으로 정리됨
• 현재 사용자 자격 증명으로 gh CLI 인증 완료
• 가능하면 GitHub Issue Form .github/ISSUE_TEMPLATE/task.yml 또는 프레임워크 원본 templates/.github/ISSUE_TEMPLATE/task.yml을 읽을 수 있음
• 이슈 생성 전 제목, 본문, milestone, label 초안을 작업지시자에게 확인받을 수 있음

절차

1. 중복 이슈 확인

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

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

1. 열린 milestone 목록 확인

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

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

1. 기존 label 목록 확인

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

• 조회 결과의 name, description을 기준으로 판단한다.
• 기억하고 있는 과거 label 목록을 기준으로 단정하지 않는다.

1. milestone 후보 선택

• 열린 milestone만 후보로 사용한다.
• 작업 목적, 범위, 대상 컴포넌트, 릴리스 단계가 조회된 milestone의 title/description과 가장 잘 맞는지 비교한다.
• 후보가 명확하면 milestone 제목과 선택 이유를 기록한다.
• 후보가 2개 이상이면 2~3개 후보와 각각의 이유를 작업지시자에게 제시하고 확인받는다.
• 적합한 열린 milestone이 없거나 설명이 부족하면 임의 선택하지 말고 작업지시자에게 확인한다.

1. 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은 만들지 않는다.

1. 이슈 초안 작성

• 제목: 작업 단위가 드러나는 한 문장
• 본문은 GitHub Issue Form .github/ISSUE_TEMPLATE/task.yml을 우선 기준으로 작성한다.
• 프레임워크 저장소에서 적용 저장소용 원본을 확인해야 하면 templates/.github/ISSUE_TEMPLATE/task.yml을 참조한다.
• gh issue create는 Issue Form UI를 실행하지 않으므로, Form의 입력 항목을 아래 Markdown 섹션으로 변환해 본문을 만든다.
• Issue Form 기준 섹션:
• 배경
• 목표
• 범위 - 포함
• 범위 - 제외
• 수용 기준
• 검증 기준
• 참고
• 마일스톤과 label 후보
• Issue Form을 읽을 수 없는 경우에만 fallback으로 위 섹션 목록을 사용한다.
• milestone: live 조회 결과에서 고른 열린 milestone 1개와 선택 이유
• label: live 조회 결과에서 고른 기존 label 0개 이상과 선택 이유
• label 선택 이유는 type/area/kind 기준으로 나누어 적고, 5개 이상이면 예외 사유를 별도로 적는다.

1. 이슈 생성 전 승인 요청

• 작업지시자에게 제목, 본문, milestone, label 초안과 선택 이유를 보여준다.
• 작업지시자가 같은 스레드에서 생성 승인을 명시하기 전에는 gh issue create를 실행하지 않는다.

1. 승인 후 이슈 생성

   gh issue create --repo {REPO_SLUG} \
     --title "{제목}" \
     --body "{본문}" \
     --milestone "{milestone}" \
     --label "{label}"

• label이 여러 개면 --label documentation --label enhancement처럼 반복한다.
• label을 쓰지 않기로 했으면 --label 옵션을 생략한다.

1. 생성 결과 확인

   gh issue view {N} --repo {REPO_SLUG} \
     --json number,title,state,milestone,labels,url

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

검증

• 생성된 이슈가 OPEN 상태여야 한다.
• milestone이 비어 있지 않고 live 조회 결과에 있던 열린 milestone이어야 한다.
• label은 초안에서 승인된 기존 label만 붙어 있어야 한다.
• 일반 이슈 label은 2~4개 권장 범위인지 확인한다.
• 5개 이상 label이면 승인된 예외 사유가 생성 결과 보고에 포함되어야 한다.
• area:* label은 주 작업 소유 영역 기준으로 선택되어야 한다.
• 이슈 본문이 .github/ISSUE_TEMPLATE/task.yml의 필수 입력에 대응하는 배경, 목표, 포함 범위, 제외 범위, 수용 기준, 검증 기준을 채워야 한다.
• 생성 결과 보고에 issue number, URL, milestone, label, 선택 이유가 포함되어야 한다.

절대 하지 말 것

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

호출 방법

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