Procedure for creating an Issue that lets implementation begin. Independent of language or stack,git と gh use only. An Issue exists to record "what is happening" and "what counts as done" in a form that another agent or person reading it later can understand without asking questions.
When to Use
- When asked to "create an Issue" or "file one"
- When trying to start implementation and there is no corresponding Issue (
issue-to-mergethe first step) - When, during requested work, you find a bug, a documentation error, or a test defect outside the requested scope
Decide where to file
gh repo view --json nameWithOwner,isFork,viewerPermission,parent \
--jq '{repo: .nameWithOwner, fork: .isFork, permission: .viewerPermission, parent: .parent.nameWithOwner}'
permissionがADMIN/MAINTAIN/WRITErepository, you may file without asking for confirmation.- Otherwise (someone else's repository, a fork's
parent), file only when the user asks you to file. If not asked, put the draft in the conversation and stop. - Do not put security defects in a public Issue. Follow the repository's reporting procedure (
SECURITY.md).
Procedure
-
Look for duplicates. If one already exists, do not create a new one; add the evidence to that Issue.
gh issue list --state all --search "<症状や対象を表す語> in:title,body" --json number,title,state,urlIf the symptoms match a closed Issue, create a new one as a recurrence and reference the original Issue in the body.
-
Gather evidence. Verify what you can verify yourself before filing.
- Versions (tool, runtime, target commit)
- Commands run and actual output (excerpt the key points; collapse long logs)
- Reproduction steps. If you could not reproduce it, say that you could not
- Clearly mark speculation as speculation. Do not mix it with verified facts
-
Write the completion criteria in an executable form. Not "fix it" or "improve it", but the command to run and the expected result. If you do not know the project's check command, look it up in
issue-to-merge's "Identify the check command". -
File it. Pass the body from a file (so shell quoting does not break it).
gh issue create --title "<対象>: <起きていること>" --body-file issue.mdAdd only labels that already exist in the repository (
gh label list). Do not create labels that do not exist. -
Report the Issue URL. If you continue with implementation, proceed to
issue-to-merge.
Body format
## 起きていること
<観察した事実。1〜3 文>
## 根拠
- 版: <ツール / ランタイム / commit>
- 実行: `<コマンド>`
- 出力:
```
<実際の出力の要点>
```
- 再現手順: <手順、または「再現できていない」>
## 期待する動作
<こうなるべき、を 1〜2 文>
## 完了条件
- `<検査コマンド>` が通る
- <観察できる結果。例: `<コマンド>` の出力に <語> が含まれない>
## 範囲に含めないこと
<今回やらないこと。無ければ節ごと省く>
- The title should state the target and the symptom. Do not make it just "the matter of ~" or "bug".
- One Issue has one set of completion criteria. Separate work that can be completed independently.
- For guesses about the cause or proposed fixes, write only the verified scope under "Evidence". Put unverified proposals under a separate "Speculation" heading.
- Match the body language to the repository's existing Issues.
Related
issue-to-merge: the overall flow from Issue to mergegoal-prompt-crafter: use completion criteria as the stopping condition for autonomous execution