SuperAPI AI Directory

issue-start

General & other

View repository

Updated 10-15 21:02

About this skill

1. 쉬운 말로 쓴다. 전문 용어를 쓸 거면 바로 옆에 풀어 준다.
2. 지금 무슨 상황인지부터 말한다.
3. 무엇이 잘못됐는지 말한다.
4. 잘못되지 않은 것도 말한다 — 무엇은 멀쩡한지 짚어 준다.
5. 사용자가 정해야 할 것을 고를 수 있게 물어본다. AskUserQuestion 을 쓴다.
6. 이슈·PR·코멘트는 `[설명](링크)` 로, 워크트리 경로는 배치에 맞는 형태로 쓴다. `링크와 경로 쓰는 법` 참고.

문제 상황이 아니어도 사용자에게 말을 걸 때는 현재 단계를 함께 밝힌다.
다음 단계로 넘어가기 직전의 전이 보고와 승인·확인 질문이 모두 대상이다. `# 현재 단계 밝히기` 를 따른다.
Overall flow State the current step

When speaking to the user, which skill and which step you are currently at must always be written together. This applies to transition reports and the body of AskUserQuestion questions, and step notation is not included in option labels.

Notation format

<스킬 이름> <n>단계(<단계 이름>)

예) issue-start 5단계(워크트리 생성)

Canonical step names

 1  인자 분기 및 전제 확인
 2  이슈 수집
 3  작업 성격 판정
 4  코드베이스 대조 분석
 5  워크트리 생성
 6  before 증거 캡처
 7  구현
 8  작업 트리 커밋
 9  after 증거 캡처
10  증거 미러 커밋·푸시
11  이슈 리포트 코멘트
12  메인 체크아웃 최신화
13  다음 행동 선택

Position is determined by length

5줄 미만   단계를 먼저 말하고, 이어서 할 말을 한다
5줄 이상   할 말을 먼저 하고, 마지막에 `현재 단계 — <표기>` 를 한 줄로 남긴다

The line count is based on the body visible to the user, and AskUserQuestion options are not counted.

Fewer than 5 lines — prepend

issue-start 5단계(워크트리 생성)입니다. 워크트리를 어디에 만들지 한 번만 정하겠습니다.

5 lines or more — append

계획을 `.issue/11/plan.md` 에 저장했습니다.

원인 가설과 검증 방법을 정리했습니다.
증거 캡처 조건도 함께 확인했습니다.
다음에는 워크트리를 만들겠습니다.

현재 단계 — issue-start 4단계(코드베이스 대조 분석)

When it is a question

Include the step notation in the question body, and do not repeat it in the options.

flowchart TD
    A[/"/issue-start {인자}"/] --> B{인자가 이슈 번호?}
    B -- 아니오 --> B1[plan 모드 전환]
    B1 --> B2[AskUserQuestion: 이슈로 등록할까요?]
    B2 -- 등록 --> B3[issue-create 설치 확인·자동 설치] --> B4[/issue-create 위임] --> C
    B2 -- 취소 --> Z0[중단]
    B -- 예 --> C{git repo + gh auth}
    C -- 실패 --> Z0
    C -- 통과 --> D[fetch: 본문·코멘트·라벨·이미지 수집]

    D --> E[issue.md 정독 + 이미지 Read 로 열람]
    E --> F{작업 성격 판정}
    F -->|UI| G1[frontend-analysis.md]
    F -->|서버| G2[backend-analysis.md]
    F -->|둘 다| G3[두 레퍼런스 모두]

    G1 --> H[코드베이스 대조 분석]
    G2 --> H
    G3 --> H
    H --> I[plan.md 저장]

    I --> J{worktree.layout 설정됨?}
    J -- 아니오 --> J1[AskUserQuestion: sibling / children] --> J2[settings.json 에 고정] --> K
    J -- 예 --> K[워크트리 생성]

    K --> L[before 캡처 · 파일 수정 전]
    L --> M[구현]
    M --> N{guard 통과?}
    N -- 아니오 --> N1[사용자 확인 후 커밋]
    N -- 예 --> N2[묻지 않고 커밋]
    N1 --> O
    N2 --> O[after 캡처 · 바운딩 박스 포함]

    O --> P[증거 커밋 + 브랜치 push]
    P --> Q[evidence-mirror --push: 기본 브랜치에 증거 커밋]
    Q --> R{비공개 저장소?}
    R -- 아니오 --> R1[evidence-urls: 미러 기준 raw URL]
    R -- 예 --> R3[evidence-urls: gh-attach 자동 업로드 시도]
    R3 --> R4{전부 성공?}
    R4 -- 예 --> S[report-check + gh issue comment]
    R4 -- 아니오 --> R2[실패한 이미지만 이슈 웹 UI 업로드: user-attachments URL]
    R1 --> S
    R2 --> S
    S --> S0{이미지 렌더링 확인}
    S0 -- 깨짐 --> R
    S0 -- 정상 --> S1[sync-base: 메인 체크아웃 최신화]
    S1 -- 막힘 --> S2[AskUserQuestion: 어떻게 받아올지] --> T
    S1 -- 성공 --> T[보고 + 다음 행동 4지선다]
Machine step API

The automatic orchestrator uses only node <skill>/scripts/issue-start.mjs phase --request <absolute-canonical-json>. The request schema is contracts/issue-start-phase-api-v1.json, and the full 13-step capability, effect, approval, checkpoint, and reconciliation contract and raw-byte closure are contracts/issue-phase-capability-bundle-v1.json. If either contract or the closure verification fails, do not start an active run.

Script path

Among the following, the first path that exists를 <skill> is used. If none exist, perform the inline procedure of each reference as is.

.claude/skills/issue-start      # 현재 프로젝트 (Claude Code)
.codex/skills/issue-start       # 현재 프로젝트 (Codex)
~/.claude/skills/issue-start    # 홈 설치
~/.codex/skills/issue-start     # 홈 설치

<skill> 이 .claude/ If under , the execution family is claude, .codex/ If under , it is codex . Use this determination for subagent model selection and automatic installation.

Subagent

Delegate deterministic tasks to a cheap model. The model for each family is owned by the agent definition file.

claude  .claude/agents/issue-verifier.md   (model: haiku)
codex   .codex/agents/issue-verifier.toml  (model = "gpt-5.6-luna")

If there is no definition, install it as follows.

sh <migrate-skill-agent>/scripts/migrate-skill-agent.sh --agent issue-verifier --target home --link --clone

If installation is refused or fails, proceed with the default subagent, but "Model pinning failed — high determination cost" report this in one line. Do not attempt to pass the model name as a Task argument. Neither runtime supports it.

Problem report format

When something is blocked or goes wrong, follow the five-line order 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 broken." 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-start <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. Your 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 the number. [설명](링크) Write it 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 constructed, write only the number and leave one line noting that fact. Do not invent links that do not exist.

Worktree paths in a form that matches the layout

ctrl+클릭 To open with , 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 to a nonexistent path. Conversely, writing children as an absolute path 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 judge for yourself, look at the actual path, not the setting. git worktree list Get the path with , and if it is under the repository root it is children, otherwise sibling. Setting values are used only when creating new ones, so an existing worktree may have been created with an old setting.

Execution order

Step 0 — Argument branching and precondition check

$ARGUMENTS First classify .

/(^|\D)(\d{1,6})\s*$/ 또는 /issues\/(\d+)/ 매치  →  이슈 번호 경로 (아래 1단계로)
매치 실패 + 비어있지 않은 텍스트                  →  작업 설명 (references/intake.md)

If it is a task description, after switching to plan mode ask with AskUserQuestion. For details, references/intake.md.

If it is an issue number path, check the preconditions.

git rev-parse --show-toplevel

Tracker authentication is fetch checked automatically by . If it fails, exit 4 it falls back to and tells you what was missing.

provider.type = github   gh 인증. 실패하면 `gh-setup` 스킬로 설치·로그인을 끝낸 뒤 이어서 진행
provider.type = jira     ~/.issue/settings.json 의 provider.jira + tokenEnv 환경변수

PRs go up on GitHub regardless of the tracker. Even if you use Jira, gh login is still required.

Step 1 — Create checklist

Create the following 13 items with TodoWrite. Update each step to completed immediately when it finishes.

1.  인자 분기 및 전제 확인
2.  이슈 수집 (본문·코멘트·이미지)
3.  작업 성격 판정
4.  코드베이스 대조 분석 + plan.md
5.  워크트리 생성
6.  before 증거 캡처 (pure 상태)
7.  구현
8.  작업 트리 커밋
9.  after 증거 캡처 (바운딩 박스 포함)
10. 증거를 기본 브랜치에 미러 커밋·푸시
11. 이슈에 전후 리포트 코멘트
12. 메인 체크아웃의 기본 브랜치 최신화
13. 다음 행동 선택

Step 2 — Issue collection

node <skill>/scripts/issue-start.mjs fetch {issue_number}

For details, references/issue-collection.md.

If collection succeeds, the script moves the progress status label to status:plan (in the output, STATUS=). Since this is a signal that the issue has been claimed, no separate call is needed. To block it, --no-status.

Step 3 — Determine the nature of the work

issue-verifier Delegate to . Use labels, body keywords, and the presence or absence of attached screenshots as evidence.

frontend 신호   스크린샷 첨부, "화면/버튼/레이아웃/깨짐/반응형", 라벨 ui·design·frontend
backend 신호    "느림/타임아웃/500/중복/정합성/쿼리", 라벨 api·performance·backend·db
both            사용자 플로우 전체를 다루거나 API 계약 변경이 화면에 영향
neither         문서·설정만 바뀜 — 캡처 대신 변경 근거를 글로 남긴다

Report the determination result and evidence in one line, then read the corresponding reference.

Step 4 — Comparative analysis and planning

Fill in the reference's investigation items. If the search scope is broad, delegate to the Explore agent. Save the plan as .issue/{issue_number}/plan.md .

Plan document structure:

  1. Issue summary — problem / requirements / completion criteria (including content read from images)
  2. Cause hypothesis — the evidence path:line
  3. Work plan — ordered list of changes, file by file
  4. Verification method — Check the repository's actual scripts to pin down the command
  5. Evidence plan — URLs, states, and viewports to capture, selectors to draw boxes with, and if it's a backend, metrics and commands to measure
  6. Open questions — if a product decision is needed, AskUserQuestion

The evidence plan in step 5 must be filled in. It is used directly in step 6, and issue-end serves as the criterion when re-verifying.

Step 5 — Create worktree

references/worktree.md . If the placement method has not been decided, ask exactly once here and fix it.

Once the worktree is up, the script writes the progress status to status:in-process . This means the code has started running.

Step 6 — before capture

Immediately after creating the worktree, before modifying even a single file, capture. The worktree at this moment is by definition pure. For details, references/evidence-capture.md.

Step 7 — Implementation

plan.md carry out the work plan in order and run the verification commands. For details, references/implementation.md.

Step 8 — Commit work tree

node <skill>/scripts/issue-start.mjs guard
git add -A -- ':!.issue'          # 증거는 이 커밋에 넣지 않는다
git commit -m "<type>(<scope>): <요약>"

If it passes, without asking the user commit. If it fails (exit 3), report the reason and get confirmation via AskUserQuestion.

':!.issue' If you omit

Step 9 — after capture

Capture with the same URL, state, and viewport as before, and add --box to the changed region. Draw boxes with the same selectors in the before as well so they can be compared at the same level.

Steps 10–11 — Mirror commit and issue comment

Keep the order and choose the image URL according to the repository's visibility. Public repositories use mirror-based raw URLs, private repositories require user-attachments URLs to render immediately. evidence-urls If gh-attach is a private repository,

node <skill>/scripts/issue-start.mjs evidence-commit {issue_number}
git push -u origin "$(git branch --show-current)"
node <skill>/scripts/issue-start.mjs evidence-mirror {issue_number} --push
node <skill>/scripts/issue-start.mjs evidence-urls {issue_number} --mirrorRef <mirror 출력의 mirrorRef>
gh repo view --json visibility --jq .visibility
node <skill>/scripts/issue-start.mjs report-check {issue_number}
gh issue comment {issue_number} --body-file .issue/{issue_number}/evidence/comment.md

evidence-urls 의 renderMode 가 auto-upload 면(= isPrivate: true and gh-attach all succeeded) images[].inlineUrl is already filled in, so use it as is. manual-upload If inlineUrl 이 null is nullimages[].autoUploadError (with the reason in uploadUrl and the corresponding images[].localPath and, after receiving the user-attachments URL 로 comment.md , publish it.

For details and the comment format, see references/evidence-capture.md.

Step 12 — Update main checkout

The evidence went straight to the default branch from the temporary worktree. The user's main folder does not yet know about that commit.

node <skill>/scripts/issue-start.mjs sync-base

Fetch only when safe. If blocked, do nothing and just return the reason, in which case decide together via AskUserQuestion. For details, references/evidence-capture.md 의 9. 메인 체크아웃 최신화.

Step 13 — Next actions

references/next-actions.md Presents the four-choice options as they are.

Closing report

이슈      [#{issue_number} <제목>](<이슈 URL>)
핵심 발견  <3줄 이내>
계획      .issue/{issue_number}/plan.md
워크트리   <WORKTREE_DISPLAY 값> (<layout>)
상태      status:in-process
브랜치    <이름>
기본 브랜치 <base> (<판별 출처>)
커밋      <구현 커밋> + <증거 커밋>
증거      before <n>장 / after <n>장 (박스 <n>개)
코멘트    [리포트 보기](<이슈 코멘트 URL>)
동기화    <메인 최신화 결과 또는 건너뛴 사유>
다음      <사용자가 고른 행동>

현재 단계 — issue-start 13단계(다음 행동 선택) 완료