Issueops Create Issue

---
name: issueops-create-issue
description: Use at the start of an IssueOps cycle, when "issueops next" reports stage none or issue, or for "이슈 만들어줘", "이슈부터 시작하자", "child task 만들어줘". Records intent and publishes a readable Korean issue.
---

# IssueOps Create Issue

**1단계 하나**를 맡는다. 할 일을 확정해 기록하고 팀이 보는 이슈로 만든다.
브랜치·계획·구현은 다음 단계다.

본문은 단독 주입·복사에도 적용된다. sibling 스킬은 설치되어 있을 때 활용하며 없으면
아래 계약과 CLI의 exact `next_command`로 진행한다. evaluator나 sibling 설치는 요구하지 않는다.
선택적 [작성 예시와 배경](references/issue-writing.md)은 symlink를 해소한 이 파일 기준이다.
초안/상태만 요청했으면 그 결과에서 끝낸다. 원격 생성 권한을 추정하지 않는다.

`execution whoami --json`의 `record_actor_flags`를 `$RECORD_ACTOR_FLAGS`,
`claim_actor_flags`를 `$ACTOR_FLAGS`로 그대로 쓴다. durable 기록 직전 exact ID·native actor·
source cwd를 대조하고, execution이 있으면 generation·holder·canonical cwd도 확인한다.
다른 holder나 불일치는 stop이다. lease 전 준비에 가짜 generation을 만들지 않는다.
`feedback add`와 `status`는 유효 root alias다. 이 단계가 인증된 feedback 기록을 맡는다.
`skill-bench`는 미구현이고 `quality inspect`는 semantic skill runner가 아니다.

## 이 스킬이 맞는지 확인

```bash
# ID가 있으면 --id "$ISSUEOPS_ID"를 붙인다. 새 사이클 선택에만 자동 판정을 쓴다.
issueops next --json
```

`none|issue`면 진행한다. 명시적인 새 사이클 요청은 다른 기존 stage/사이클과 무관하게
허용한다. 그 밖에는 `next`가 지목한 단계로 간다. `blocked.*`를 우회하지 않는다.

`start`는 **source checkout**에서만 실행한다. worktree를 record의 repo로 만들지 않는다.

`next`가 기존 사이클을 선택했지만 사용자가 별도의 새 사이클을 명시적으로 요청했다면
첫 명령에 `--new`를 붙인다. `--new`는 `--branch`와 함께 쓸 수 없고 실행할 때마다 새 lifecycle ID를
만든다. 응답을 받았는지 불분명하면 같은 명령을 다시 실행하지 않고 먼저 `issueops list --repo "$SOURCE_ROOT" --json`으로
확인한다. 성공 응답의 ID를 이후 명령에 계속 사용한다.

## 입력 세 가지

세 입력의 조사 출처를 plan-prep evidence 문자열로 남긴다. 조사 방법 전문은
[입력 조사](references/input-research.md)를 읽고 따른다.

1. **사용자가 준 정보.** 원문을 그대로 intent contract의 `--raw-request`에 넣고 요약해 대체하지 않는다.
   기획서·화면 캡처는 설치된 `requirements-analysis`로 먼저 추출해 제약은 `intent record --constraint`에,
   모순과 누락은 `--ambiguity`에 넣는다.
2. **코드베이스 조사.** 만진 심볼·파일·호출 경로를 `--codebase-survey-evidence`에 적고, 이 요청에 걸리는
   ADR·CAUTIONS 항목의 문서 경로와 제목(없으면 대조한 문서 목록)을 `--decisions-evidence`에 적는다. 걸린
   기록은 열어서 이 요청의 범위나 방식을 정하는지 판정하고, 열어 보지 않고 "해당 없음"으로 적지 않는다.
   `.issueops/CONSTITUTION.md`의 원칙에 걸리면 성공 기준이나 제약으로 이슈 본문에 옮긴다.
3. **배경지식과 웹 조사.** 외부 API의 의미나 계약이 걸릴 때만 직접 조사해 `--web-research-evidence`에
   넣는다. 조사하지 않았으면 waive하지 말고 왜 필요 없는지를 evidence로 쓴다. 관련 이슈는
   `--related-score-ref`로 남긴다.

원격 이슈를 쓰기 전에 `.issueops/AGENT_WORKFLOW.md`의 Start·Work 절을 읽는다. Work 절이
가리키는 `.issueops/VCS.md`가 있으면 provider recipe와 CLI 대체 경로를 거기서 확인한다.

## 질문 규칙

모호함을 세 갈래로 나눠 원장처럼 관리한다.

| 분류 | 뜻 | 처리 |
|---|---|---|
| `resolved` | 조사로 답이 나왔다 | 이슈 본문의 근거 절에 답과 출처를 쓴다 |
| `deferred` | 지금 몰라도 구현 방향이 바뀌지 않는다 | 이슈 본문 "열린 결정" 절에 남긴다 |
| `blocking` | 답에 따라 다른 것을 만들게 된다 | 사용자에게 묻는다 |

- **blocking만 묻는다.** 조사로 답할 수 있는 것은 먼저 조사한다.
- 한 번에 한 질문만 한다. 선택지가 있으면 번호로 제시하고 추천안을 먼저 둔다.
- 답을 받으면 그 답이 무엇을 바꾸는지 한 문장으로 되돌려 확인한다.
- 다음을 확인할 때까지 이슈를 만들지 않는다: 사용자에게 보이는 문제와 지금 중요한
  이유, 테스트와 실제 표면으로 검증 가능한 성공 기준, 비목표와 범위 경계, 근거가 필요한
  도메인 용어, 필요한 파일·API·명령·런타임 표면, 구현을 실질적으로 바꿀 열린 결정.

blocking 질문이 둘 이상이거나 답에 따라 만들 것이 갈리면 드래프트를 먼저 만들고,
한 번에 한 질문만 하며 매 답변 뒤 남은 모호함을 확인한다. 설치된 `implementation-planning`의
인터뷰를 활용한다. 드래프트의 `Requirements (confirmed)` 절이 intent contract
`--interpreted-intent`의 원문이 된다. 확정 뒤 드래프트는 지운다 — 이슈 본문이 유일한
계약이다.

## 기록 순서

아래 기록 순서를 지킨다. 항목이 비면 grill 진입이 거부된다.

```bash
issueops start --repo "$SOURCE_ROOT" --json      # ISSUEOPS_ID를 받는다
# 기존 사이클과 별도의 새 사이클을 요청한 경우에만 위 명령에 --new를 붙인다.

issueops intent record --id "$ISSUEOPS_ID" \
  --raw-request "<사용자 원문>" --interpreted-intent "<해석>" \
  --success-criteria "<검증 가능한 기준>" --intent-class trivial|standard \
  [--non-goal "<하지 않을 것>"] $RECORD_ACTOR_FLAGS --json   # --non-goal은 반복 가능, 봉인된 intent.md의 비목표

issueops domain-review record --id "$ISSUEOPS_ID" \
  --model-fit "<도메인 모델과 이 변경의 관계>" $RECORD_ACTOR_FLAGS --json

# 분할 여부를 지금 결정으로 남긴다(split_decision). 분할하지 않으면 그 근거를 쓴다.
issueops decision add --id "$ISSUEOPS_ID" --kind scope \
  --title "no split" --body "<한 owner·한 리뷰로 끝나는 근거>" $RECORD_ACTOR_FLAGS --json
# 분할하면 title을 "split: <child 목록>"으로 쓴다. child는 branch prepare 뒤에 만든다(아래 Parent와 child).

# 관련 이슈·라벨 점수는 plan-prep보다 먼저 만든다. 그 요약이 --related-score-ref다(입력 형식은 발행 세부 규칙).
issueops remote score --input "$SCORE_INPUT" --judge none --json > "$SCORE_FILE"
# 선택하거나 거절한 라벨과 threshold는 본문이 아니라 record에 남긴다.
issueops decision add --id "$ISSUEOPS_ID" --kind review --title "라벨 판단" \
  --body "<threshold, 선택한 라벨, 거절한 라벨, override 여부>" $RECORD_ACTOR_FLAGS --json

issueops plan-prep record --id "$ISSUEOPS_ID" \
  --decisions-evidence "<...>" --related-score-ref "<score 결과의 선택·거절 후보와 threshold 요약>" \
  --web-research-evidence "<...>" --codebase-survey-evidence "<...>" \
  $RECORD_ACTOR_FLAGS --json

issueops phase --id "$ISSUEOPS_ID" --to grill $RECORD_ACTOR_FLAGS --json
```

다음은 원격 write다. 초안을 보여 주고 요청에 발행이 포함되어 있으면 아래 publication
절차로 재승인 없이 진행한다. 승인받은 특정 원문이나 범위를 바꿨으면 먼저 확인받는다.

`remote create-issue` 뒤 `status --json`에 `issue_url`이 없을 때만
`issueops link-issue --id "$ISSUEOPS_ID" --issue-url "$ISSUE_URL" $RECORD_ACTOR_FLAGS --json`을 실행한다.
사용자가 기존 이슈(번호나 URL)를 처리하라고 하면 새로 만들지 않는다. 처리 절차는
[발행 세부 규칙](references/publication-details.md)을 읽고 따른다.

이슈만 요청했으면 다음 세 줄로 완료 보고한다. 전체 작업 요청이면 진행 상황으로 알린 뒤
같은 ID로 `issueops-prepare`를 실행한다. worktree 준비 후 환경별 자동 세션 인계를 적용한다.

```text
ISSUEOPS_ID: <id>
issue: <url>
다음 단계: issueops-prepare
```

## 먼저 고르는 것

| 요청 | 사용할 형식 | 분리 기준 |
|---|---|---|
| 결함·회귀 | `bug` | 재현 절차와 기대/실제 동작을 숫자 목록으로 쓴다 |
| 사용자 기능 | `feature` | 사용자 가치와 완료 조건을 짧은 checklist로 쓴다 |
| 구조·정책 결정 | `proposal` | 대안 비교가 핵심이면 표와 결정 근거를 쓴다 |
| 바로 실행할 작업 | `implementation_task` | 근거·범위·검증을 중심으로 쓴다 |
| parent의 독립 작업 | `child_task` | scope·의존성·wave를 metadata 표로 쓴다 |

**결론은 요약, 근거는 배경, 명령은 검증 절**에 둔다. 다이어그램은 흐름·상태·경계를
문장보다 빨리 이해할 때만 쓴다.

## Parent와 child

기본은 `no split`이다. 한 owner의 검토 가능한 변경이면 아래 근거를 parent에 남긴다.

```text
Large Issue Breakdown Gate: no split
- 독립적인 acceptance와 rollback 경계가 없다.
- 한 owner와 한 MR로 검토할 수 있다.
- 이번 범위는 <파일/모듈> 안에 머문다.
```

다음 중 하나가 있을 때만 split한다.

- 한 Issue에 두면 독립된 delivery·rollback·review가 숨겨진다.
- 사용자가 병렬 ownership 또는 assignee 분리를 명시했다.
- 같은 수정을 여러 base 브랜치에 넣는다(release hotfix와 main 반영 같은 backport). 브랜치마다 PR이 따로
  나오므로 child로 나눈다. 한 이슈에 사이클 둘을 걸면 첫 사이클의 정리가 이슈를 닫고, 이슈 본문의
  계획 검토·진행 결과 구간을 두 사이클이 번갈아 덮어쓴다.

split하면 [분할 절차](references/child-split.md)를 읽고 따른다. `[p]`/`[s]` 실행 class, parent의
`## 하위 Task` 기록, `remote create-child`와 `--operation-id`·reconcile 복구가 거기에 있다.

## 읽기 좋은 body

절 구성은 `issueops remote render-template`이 출력하는 골격을 따른다. 사람이 읽을
문제·범위/비목표·완료 기준·실행 가능한 검증 명령과 기대 결과를 채운다.

```bash
issueops remote render-template --kind issue --template "$TEMPLATE" \
  --provider "$PROVIDER" --title "$TITLE" --json
```

child 본문은 `--kind child --template child_task`로 렌더한다(`--kind issue`는 child_task를 거부한다).
빈 골격의 `ok:false`는 아직 채우지 않은 필수 필드 목록이며 실패가 아니다.

로그는 secret을 제거한 짧은 code block으로만 붙인다. 긴 로그 전체나
스크린샷 대신 재현에 필요한 줄과 파일·명령을 적는다. 해시, 커밋 SHA 전문,
라벨 점수, plan 원문·repo-local plan 경로·`Plan Link`·`TBD`는 본문에 넣지 않는다.
plan-prep 네 항목은 waive로 채우지 않는다. 조사 결과나 불필요한 이유를 evidence로 쓴다.

## Canonical publication

1. 현재 provider 이슈·label 후보를 조사한다. 일치하는 이슈가 있으면 중복 생성 대신
   연결/갱신한다. 선택된 label·관련 이슈만 적용하고(score 기본 threshold 0.70) 무라벨 발행은 하지 않는다.
2. semantic 판단이 필요하면 `remote score --judge prompt`를 fresh 독립 read-only agent에게 주고 결과 JSON을
   `--judge file --judge-file`로 검증한다. 독립 agent가 없으면 deterministic 결과를 쓰고 그 선택을
   기록한다. override·`abstained`·label 생성 규칙은 [발행 세부 규칙](references/publication-details.md)을
   읽고 따른다.
3. 한국어 본문을 `fluent-korean` 스킬로 다듬는다. issueops와 함께 설치되므로 생략하지 않는다(원격 쓰기의
   선행 조건, `issueops-remote-write` 규칙 2). secret을 제거하고 실제
   assignee를 확인한다(`@me` 금지). 사용자가 따로 정하지 않았으면 인증된 사용자를 쓴다:
   `gh api user --jq .login` 또는 `glab api user`의 `username`. git 이메일에서 추측하지 않는다.
   설치된 `issueops-remote-write`를 활용할 수 있다.
4. body file을 읽고 preview의 `readability`를 확인한다. critical은 수정 후 재preview,
   warning은 수정하거나 이유를 기록한다. preview와 동일한 요청에만 `--confirm`을 붙인다.
5. URL·상태·본문 hash·label·assignee·hierarchy를 readback한다. 새 이슈의 본문 baseline은
   `status.issue_create_intent.body_sha256`이다. `body_syncs`는 첫 `sync-issue` 뒤에 생긴다.
   모호한 issue 생성은 `remote reconcile-issue --id ID --json`으로 확인하며 재생성하지 않는다.
   raw provider CLI/MCP 쓰기로 우회하지 않는다. 둘 이상의 artifact면 중단한다.

```bash
# create-issue는 actor 플래그를 받지 않는다(넘기면 flag 오류). 미리보기 뒤 같은 요청에 --confirm.
issueops remote create-issue --id "$ISSUEOPS_ID" --provider "$PROVIDER" \
  --title "$TITLE" --template "$TEMPLATE" --body-file "$BODY_FILE" \
  --label "$LABEL" --assignee "$ASSIGNEE" --json
```

## 품질·성능 게이트

- 품질: preview의 `readability.critical` 0, warning 처리 기록, 원격 write 전
  한국어 검토(`fluent-korean` 호출), 라벨 판단 decision 기록, secret redaction,
  hierarchy/label/assignee readback.
- 성능: issue 단계에서만 이 스킬을 로드한다. PR/MR reference를 함께
  중복 로드하지 않는다. 변경 전후 byte 수와 focused 검증 시간을 기록하되
  측정 없는 성능 개선을 주장하지 않는다.

provider, project authority, owner, body, label/assignee, hierarchy, 또는
durable intent가 모호하면 쓰지 않는다.