1. 쉬운 말로 쓴다. 전문 용어를 쓸 거면 바로 옆에 풀어 준다.
2. 지금 무슨 상황인지부터 말한다.
3. 무엇이 잘못됐는지 말한다.
4. 잘못되지 않은 것도 말한다 — 무엇은 멀쩡한지 짚어 준다.
5. 사용자가 정해야 할 것을 고를 수 있게 물어본다. AskUserQuestion 을 쓴다.
6. 이슈·PR·코멘트는 `[설명](링크)` 로, 워크트리 경로는 배치에 맞는 형태로 쓴다. `링크와 경로 쓰는 법` 참고.
문제 상황이 아니어도 사용자에게 말을 걸 때는 현재 단계를 함께 밝힌다.
다음 단계로 넘어가기 직전의 전이 보고와 승인·확인 질문이 모두 대상이다. `# 현재 단계 밝히기` 를 따른다.
Overall flow
State the current stage
When speaking to the user, which skill and which stage it is currently at must always be written together. This applies to transition reports and the body of AskUserQuestion questions, and the stage notation is not included in the option labels.
Notation format
<스킬 이름> <n>단계(<단계 이름>)
예) issue-end 10단계(PR 생성)
Canonical stage names
1 상황 판단
2 승인·증거 완결성 확인
3 before 재캡처 (pure-tree)
4 after 재캡처·보강
5 리포트 작성·보강
6 게시 상태 확인·필요 시 재게시
7 재게시 시 메인 체크아웃 최신화
7.5 private 이미지 업로드 (private 저장소일 때만)
8 리포트 코멘트 확인·필요 시 갱신
9 검토 승인 확인
10 PR 생성
11 다음 행동 선택
Position is determined by length
5줄 미만 단계를 먼저 말하고, 이어서 할 말을 한다
5줄 이상 할 말을 먼저 하고, 마지막에 `현재 단계 — <표기>` 를 한 줄로 남긴다
The number of lines is based on the body visible to the user, and AskUserQuestion options are not counted.
Fewer than 5 lines — prepend
issue-end 6단계(게시 상태 확인·필요 시 재게시)입니다. 게시본과 달라진 증거를 다시 올리겠습니다.
5 lines or more — append
게시된 증거와 로컬 증거가 일치합니다.
이슈 리포트도 이미 렌더링됩니다.
검토 승인 인계를 확인했습니다.
PR 생성은 그 다음에 따로 묻겠습니다.
현재 단계 — issue-end 9단계(검토 승인 확인)
When it is a question
Include the stage notation in the question body, and do not repeat it in the options.
flowchart TD
A[/"/issue-end"/] --> B[context: 워크트리·브랜치·이슈·PR·증거 상태]
B --> C{상황 확인}
C -- 워크트리 아님 / 이슈 불명확 --> C1[AskUserQuestion] --> D
C -- 정상 --> D{evidenceComplete?}
D -- 아니오 --> E1[pure-tree: 변경 직전 워크트리]
E1 --> E2[before 재캡처] --> E3[pure-tree --remove] --> F
D -- 예 --> F{evidencePublished?}
F -- 아니오 --> G[누락·변경 증거와 comment.md 보강]
G --> H[증거 커밋 + 브랜치 push]
H --> I[evidence mirror --push]
I --> I1[sync-base: 메인 체크아웃 최신화]
I1 -- 막힘 --> I2[AskUserQuestion: 어떻게 받아올지] --> J
I1 -- 성공 --> J[gh issue comment 갱신]
F -- 예 --> K{게시 리포트 승인됨?}
J --> K
K -- 아니오 --> N
K -- 예 --> L{PR 만들까?}
L -- 예 --> M["gh pr create · 관련 이슈 #N (Closes 금지)"]
L -- 아니오 --> N
M --> N[다음 행동 4지선다]
N -->|merge| O[/issue-merge 위임/]
N -->|다른 이슈| P[/issue-start 위임/]
N -->|새 이슈| Q[/issue-create 위임/]
N -->|종료| R[보고]
Machine stage API
The automatic orchestrator uses only node <skill>/scripts/issue-end.mjs phase --request <absolute-canonical-json>. The request schema is
contracts/issue-end-phase-api-v1.json, and the full 11-stage capability, effect, approval, checkpoint, and
reconciliation contract and raw-byte closure are contracts/issue-phase-capability-bundle-v1.json.
Human evidence/report approval, branch push approval, and PR creation approval are not merged, and if the contract or
closure verification fails, the active run is not started.
Among the following, the first path that exists를 <skill> is used. If none exist, use the inline procedure of each reference.
.claude/skills/issue-end # 현재 프로젝트 (Claude Code)
.codex/skills/issue-end # 현재 프로젝트 (Codex)
~/.claude/skills/issue-end # 홈 설치
~/.codex/skills/issue-end # 홈 설치
<skill> 이 .claude/ If under , the execution family is claude, .codex/ If under , codex 다.
claude .claude/agents/issue-verifier.md (model: haiku)
codex .codex/agents/issue-verifier.toml (model = "gpt-5.6-luna")
If not, install with migrate-skill-agent.sh --agent issue-verifier --target home --link --clone .
If it fails, proceed with the default subagent and report "model pinning failed" in one line.
When something is blocked or goes wrong, follow the order of the five lines below exactly. Do not change the order or skip any.
1. 상황 지금 어디까지 왔고 무엇을 하려던 중인지
2. 문제 무엇이 잘못됐는지
3. 멀쩡한 것 무엇은 문제가 없는지 (사용자가 피해 범위를 알아야 한다)
4. 원인 왜 그렇게 됐는지 (아는 만큼만. 모르면 모른다고 쓴다)
5. 선택 사용자가 정해야 할 것 — AskUserQuestion 으로 고를 수 있게
Write in plain language. Use technical terms only when absolutely necessary, and when you do, explain them right next to them.
나쁜 예 detached HEAD 상태에서 rebase 충돌로 인해 워크트리가 dirty 합니다.
좋은 예 지금 워크트리(이슈 하나를 위해 따로 만든 작업 폴더)에 저장 안 된 변경이 남아 있습니다.
Always write "what is not a problem". The user wants to know first and foremost how far things are broken.
문제 증거 이미지를 기본 브랜치에 올리지 못했습니다.
멀쩡한 것 코드 변경과 커밋은 그대로 남아 있습니다. 이슈도 그대로입니다.
The last line is always a question. Do not end without the user knowing what they need to decide. Use 2–4 options, put the recommended option first, and write the result of each choice in one line.
Example
상황 이슈 #59 의 코드 변경과 커밋까지 끝냈고, 증거를 기본 브랜치에 올리는 중이었습니다.
문제 기본 브랜치가 보호되어 있어 올리지 못했습니다.
멀쩡한 것 코드 변경, 커밋, 작업 브랜치 push 는 모두 끝났습니다. 잃은 것은 없습니다.
원인 저장소 설정에서 main 브랜치에 직접 push 를 막아 둔 것으로 보입니다.
질문: issue-end <n>단계(<단계 이름>)입니다. 증거를 어디에 올릴까요?
- 별도 브랜치에 올리기 (권장) evidence/issue-59 브랜치를 만들어 올립니다. 이슈의 이미지는 정상 표시됩니다.
- 이미지를 직접 첨부 이슈 웹 페이지에 이미지를 끌어다 놓습니다. 손이 한 번 더 갑니다.
- 증거 없이 진행 이미지 없이 글로만 남깁니다. 나중에 확인이 어려워집니다.
How to write links and paths
When referring to issues, PRs, and worktrees in reports, questions, and closing summaries, follow the rules below. The four skills (issue-create / issue-start / issue-end / issue-merge) use the same rules.
Issues, PRs, and comments must always be clickable
Do not paste a bare URL as is or write only a number. [설명](링크) Write in the format.
나쁜 예 이슈 #59 탭 활성 상태 초기화
코멘트 https://github.com/owner/repo/issues/59#issuecomment-123
좋은 예 이슈 [#59 탭 활성 상태 초기화](https://github.com/owner/repo/issues/59)
PR [#103 fix(tab): 활성 상태 유지](https://github.com/owner/repo/pull/103)
코멘트 [리포트 보기](https://github.com/owner/repo/issues/59#issuecomment-123)
The address is already in hand. Do not assemble it yourself.
gh issue view <n> --json url 이슈 주소
gh pr view <n> --json url PR 주소
gh issue comment ... 의 출력 방금 단 코멘트 주소
issue-end context 출력의 issueUrl / openPr.url
issue-merge inventory 출력의 issueUrl / pr.url
If the repository cannot be identified and the address cannot be created, Write only the number and leave that fact in one line. Do not invent links that do not exist.
The worktree path should be in a form that matches the layout,
ctrl+클릭 and for it to open as such, the form must match the layout.
children 저장소 안 → 상대 경로 .issue/worktrees/59-tab-active-state
sibling 저장소 밖 → 절대 경로 /Users/me/work/repo-issue-59
If you write a sibling as a relative path, it becomes ../repo-issue-59 and opens as a nonexistent path. Conversely, if you write children as an absolute path, it is needlessly long.
Use the value the script has already computed as is.
issue-start.mjs worktree 출력의 WORKTREE_DISPLAY=
issue-end.mjs context 출력의 worktrees[].display
issue-merge.mjs inventory 출력의 worktrees[].display / excluded[].display
If you must decide yourself, look at the actual path, not the setting. git worktree list Get the path with this; if it is under the repository root, it is children, otherwise it is sibling. Setting values are only used when creating a new one, so an existing worktree may have been created with an old setting.
Step 0 — Assess the situation
node <skill>/scripts/issue-end.mjs context
Read the isLinkedWorktree / issue / evidenceComplete / evidencePublished /
evidencePublishedRef / onBaseBranch / openPr / isPrivate in the output and branch.
isPrivate: true If so, the image URL cannot be determined in step 5. This means step 7.5 is added, so include it in the step 1 checklist in advance.
For details, see references/context-triage.md.
Step 1 — Create checklist
Use TodoWrite to create the 11 items below. For a private repository, step 7.5 is added, making 12 in total. As soon as each step ends, immediately update it to completed.
1. 상황 판단 (context)
2. 검토 승인·증거 존재·완결성 확인
3. 누락 시 pure-tree 로 before 재캡처
4. 필요 시 현재 커밋 상태로 after 재캡처·보강
5. 필요 시 리포트 보강 (comment.md)
6. 게시 상태 확인·필요 시 재게시
7. 재게시 시 메인 체크아웃의 기본 브랜치 최신화
7.5 이미지 업로드받아 comment.md 의 이미지 URL 교체 (private 저장소일 때만)
8. 리포트 코멘트 확인·필요 시 갱신
9. 게시 리포트 검토 승인 확인
10. PR 생성
11. 다음 행동 선택
evidencePublished: true In a normal handoff where this is the case, only check steps 48 and do not repeatedly post.
false 면 4Step 8 is the mandatory recovery path before the PR.
Steps 2–4 — Reconfirm evidence
issue-start The evidence and posted version created by reconfirm.
evidenceComplete: false 면 pure-tree Create the state immediately before the change and take the before shot again.
For details, see references/evidence-recheck.md.
Steps 5–10 — Check posting status, conditionally supplement, PR
references/report-and-pr.md . If the posted version is the same as the current local evidence, omit reposting and comment updates.
If the evidence is insufficient or changed after posting, finish supplementing/reposting, then move on to the PR.
In step 10, immediately after creating the PR, move the progress status to status:review . Unlike other transitions, this one is not automatic.
node <skill>/scripts/issue-end.mjs status {issue_number} review
Step 7 (update main checkout to latest) does not block the flow. If it was skipped because it was unsafe, decide together with the user, and if the decision is delayed, finish the rest first and write the result in the final report.
Step 11 — Next action
references/next-actions.md Present the 4-choice options from
Final report
이슈 [#{issue_number} <제목>](<이슈 URL>)
브랜치 <이름>
워크트리 <context 의 worktrees[].display 값>
기본 브랜치 <base> (<판별 출처>)
증거 before <n>장 / after <n>장 (박스 <n>개)
미러 <mirrorRef> (fallback 이면 그 사실 명시)
코멘트 [리포트 보기](<이슈 코멘트 URL>) (신규 / 기존 갱신)
PR [#<번호> <제목>](<PR URL>) 또는 "만들지 않음 — 사유"
상태 status:review (실패했으면 그 사실)
동기화 <메인 최신화 결과 또는 건너뛴 사유>
다음 <사용자가 고른 행동>
현재 단계 — issue-end 11단계(다음 행동 선택) 완료