quick-issue

# Quick Issue 正式な開発フロー（`/grill-me` → `/to-plan` → `/to-issues`）を経由せず、**確認なしで即座に** GitHub Issue を1件起票するスキル。スライス分割・依存関係の整理・ユーザーへの確認は行わない。手早く起票することが目的。 正式フローでまとまった作業を Issue 化したい場合は `/to-issues` を使うこと。本スキルは単発の軽量起票専用。 ## 貫く原則：コールドスタート再現性 起票する Issue は **この会話を一切知らない別セッション** が読んで着手する。判断基準は一文： > この Issue 本文だけで、会話を知らない実装者が着手できるか。 手早く起票することと、単独で読めることは対立しない。速さのために削ってよいのは**推敲**であって**情報**ではない。会話の中にしか無い事実は、面倒でも本文に書き写す。 <cold-start-rules> | ルール | 書き方 | 守らないと起きること | | ---------------------------- | ---------------------------------------------------------- | ------------------------------------ | | 会話依存の指示語を使わない | 「上記の」「さっきの」「この件」を禁じ、対象を毎回名指す | 何を指すか復元できず着手できない | | 場所を名指しする | ファイルパス・シンボル・実行したコマンド・エラー出力を書く | 別セッションが探索からやり直しになる | | 確認済みの事実と推測を分ける | 確かめたことは事実として、未確認は「未確認」と書く | どこまで再調査すべきか判断できない | | 却下した案を書く | 取らないと決めた方法を理由ごと書く | 同じ案が蒸し返される | </cold-start-rules> ## このスキルの方針 - **確認不要**：ユーザーへの問い返し（AskUserQuestion・承認待ち）は行わず、与えられた情報からそのまま起票する（唯一の例外は「入力の解釈」で述べる、起票内容がまったく不明な場合の1行確認）。 - **既存の規定の違反に自分で気づいたときは、それを今後防ぐ仕組み（hook・検査スクリプト・CI ジョブ・レビュー項目）の新設を起票しない**：起票するのは壊れている成果物の修正だけで、仕組みの新設を起票してよいのは人間に指摘されたときに限る（[policy-driven-development-policy](../../../docs/policy/policy-driven-development-policy.md) が正典）。 - **デフォルトで自分にアサイン**：`--assignee @me` を付与する。 - **ラベルは後述の「付与するラベル」に従う**：ユーザーが別のラベルを指定した場合は追加で並べ、本スキルが付けるラベルは外さない。 - テンプレートの全セクションを本文に必ず含める。「対応方針」と「人間に決めてほしいこと」だけは、各セクションの条件に従って片方だけを書く。 ## 付与するラベル | ラベル | 付与条件 | 何のためか | | ---------------------------- | ------------------------------------------------------------ | -------------------------------------------- | | `boy-scout` | 無条件 | 正式フローを経ずに積んだ課題を後で棚卸しする | | `ai-fixable` | 中身を見ずに AI が直せる（下記の名指し例外に当たらない） | AI が `/sweep` でまとめて片付ける対象を選ぶ | | `issue:needs-human-decision` | 中身を見ずには直せない（下記の名指し例外のいずれかに当たる） | 人間が1件ずつ方針を決める対象を選ぶ | | `policy-gap` | 判定時に該当ポリシー・rules が見つからなかった | 後でポリシーを足す候補を拾う | `issue:needs-clean-session` と `issue:decided` は**起票時には付けない**。前者は `/sweep` が着手したうえで観測した事実で貼り、後者は `/issue-decide` で人間が方針を決めたときに貼る。どちらも起票時には判断材料が無い。 `ai-fixable` と `issue:needs-human-decision` は排他で、**必ずどちらか一方だけを付ける**。どちらも付かない Issue は、一斉対応からも個別相談からも漏れて誰の目にも触れなくなる。`policy-gap` はこの2値と直交する付加ラベルで、どちらに重ねてもよい。 ### どちらを付けるか `ai-fixable` は中身を見ずに `/sweep` へ流す対象を選ぶラベルなので、**着手してみないと何をするか決まらない Issue には付けない**。 **既定は `ai-fixable`** である。次の例外に当たるときだけ `issue:needs-human-decision` に切り替える。どちらも付けない選択肢は無い（例外に当たるかどうか迷ったら `issue:needs-human-decision` を付ける）。 - **不可逆・外部に出る**：ファイル削除・公開・本番操作・外部サービス設定 - **要件／プロダクト方針が変わる**：「何を作るか」に触れる - **ポリシー同士が正面衝突している**：どちらを優先するかの裁定が要る - **比較に実測が要り、その手段が今ない**：性能・コストのトレードオフ - **恒久的に保守が要る資産を新設する**：新規スクリプト・hook・CI ジョブ・外部依存の追加 - **書くべき設計書がまだ無い**：「書き先を決める」のどれにも当たらなかった - **着手前に仕様を詰める対話が要る**：`/grill-me` で詰めてから sub-issue に割る親Issue（新規開発ガイドの起点Issue） 「恒久的に保守が要る資産」の例外は**新設**にだけ効く。既存ファイルの編集・ドキュメント／ポリシーの改訂・既存設定へのルール追加は当たらない。足した仕組みは以後ずっと保守が要るので、増やすかどうかは人間が決める（refined-engineer-judgment-principles「コードは負債」）。 **「案が2つ以上ある」ことは `issue:needs-human-decision` の理由にならない。** 推奨案が立つなら、その根拠と却下案を「対応方針」に書いて `ai-fixable` を付ける。ポリシーが裁定できる問いを人間に戻すと、AI に判断を委譲する仕組みが成立しない（CLAUDE.md「原則から明確に答えが出るなら AI が自分で決めてよい」）。 | 例 | ラベル | なぜ | | ------------------------------------------------------ | ---------------------------- | ------------------------------------ | | タイポ・表記ゆれ | `ai-fixable` | 例外に当たらない | | 新しい判断基準をどの文書に置くか | `ai-fixable` | 案は複数だがポリシーが裁定できる | | 既存の静的解析設定にルールを1つ足す | `ai-fixable` | 既存の仕組みの手直しで、新設ではない | | 参照先の実在を検証するスクリプトと CI ジョブを新設する | `issue:needs-human-decision` | 恒久的に保守が要る資産の新設である | | ポリシーAとBが逆のことを言っている | `issue:needs-human-decision` | ポリシー同士が正面衝突している | | 使わなくなったディレクトリを消すか | `issue:needs-human-decision` | 不可逆である | | 画像アップロードの仕様を書く設計書がまだ1件も無い | `issue:needs-human-decision` | 書くべき設計書がまだ無い | ### `policy-gap` をいつ付けるか 上の判定をする前に、**該当するポリシー・rules を必ず探す**（`docs/policy-hub.md`・`.claude/rules/`）。探して**見つからなかった**ときに `policy-gap` を重ねて付ける。付けること自体はポリシー新設を意味せず、後の棚卸しの材料である。瑣末な件は棚卸しで捨てればよい。 ## 処理フロー ### 1. 入力の解釈 引数または直前の会話コンテキストから、起票したい内容を読み取る。情報が薄くても**起票を止めず**、読み取れた範囲でタイトルと本文を組み立てる。 - **タイトル**：内容が一目で伝わる簡潔な日本語（目安40文字以内）。プロジェクトの用語集（`docs/project-context/glossary.md`）の語彙に寄せる。 - 起票内容がまったく不明な場合のみ、起票せずユーザーに1行確認する。 ### 2. 本文の組み立て 下記テンプレートに沿って本文を作る。テンプレートの指示は「型」なので、埋めるだけにして書き方を自分で決めない。「タスク一覧」は読み取れる範囲でチェックボックスに分解する（不明なら最小限の1〜2項目でよい）。設計書・`docs/requirements.md`（要件定義）に書くことがあるなら、その作業もタスクに含める。**まだ無い設計書を新しく作る作業も含む**（CLAUDE.md 仕様駆動ルール）。 <destination-rules> **「対応方針」を書く前に、内容の書き先を上から順に当てる。** 既存ファイルが1件しか無いことは、そこを選ぶ理由にならない。 - **技術・アーキテクチャ・後から変えにくい決定**：ADR（`docs/adr/NNN-slug.md`）。迷ったら ADR 扱いにする - **「何を作るか」が変わる**：要件定義書（`docs/requirements.md`） - **既存の設計書の記述が間違っている、または明確に欠けている**：その設計書 - **コード・設定の修正だけで完結する（文書に残す決定を含まない）**：文書への書き先は不要。`ai-fixable` の判定へ進む - **上のどれにも当てはまらない**：**書き先はまだ無い**。`issue:needs-human-decision` を付ける ADR に当たるかの詳しい判定は [/create-adr](../create-adr/SKILL.md) の「ADR判定基準」が正典。 既存の設計書を選ぶのは「既存だから」ではない。**そのファイルが間違っている・欠けているから書く**のであって、書こうとしている内容がそのファイルの扱う範囲の外なら、その行には当たらず「書き先はまだ無い」へ落ちる。 書き先がまだ無いとき、設計書を勝手に新設してはならない。「人間に決めてほしいこと」の論点を「どの設計書を作って、そこに何を書くか」にする。設計書の新規作成は CLAUDE.md の開発フロー表で `/design` の担当であり、`/sweep` の一括処理で作ると、1 Issue 分の視野しか持たない設計書が既成事実になる。 </destination-rules> <writing-rules> **文体**：中学生が一度で追える文で書く。専門用語は使ってよい。読みにくさの原因は用語ではなく言い回しにある。 - ❌ その位置づけが実効を持たない → ✅ そう書いてあるだけで守られない - ❌ 変更耐性の最大化を企図する → ✅ 変更に強くしたい - ❌ 根拠を取り逃がす → ✅ 使えるはずの理由を見逃す - ❌ 担保する・企図する・起因する → ✅ 保つ・ねらう・原因である 一文に主語と述語は1組まで。長い一文は切る。 **用語**：本文で初めて出す用語・略語・その場の造語・ファイルの置き場所には、一行の言い換えを付ける。**本文の全節が対象**。書いた本人しか知らない語を説明なしに使うと、別セッションは何の話か分からないまま止まる。 **図**：次のどれか1つでも当てはまるときだけ、`/design-doc-mermaid` で図を描いて「この変更が必要な理由」の直後に埋め込む。当てはまらないなら描かない。 - **登場するファイル・仕組みが3つ以上あり、その参照が一直線でない（分岐・合流・双方向がある）**：複数の Skill が同じ policy を参照し、policy 側が別の Skill を呼び返す - **条件で振る舞いが分かれる、またはループする**：失敗時にリトライする処理 - **状態が移る（未着手→作業中→完了 のような遷移）**：Issue ラベルの遷移規則 自前で Mermaid を書き起こしてはならない（CLAUDE.md）。 </writing-rules> <issue-template> ## この変更が必要な理由 **1文1行で、改行して3行書く**（1段落にまとめない）。実装の詳細（HOW）は書かない。別セッションの実装者が、判断に迷ったとき優先順位を自力で決められる状態を目指す。 - **1行目**：何が困っているか。対象をパスかシンボルで名指す - **2行目**：実際に起きたことを1つ（数えた件数・実際の文言・エラー出力など） - **3行目**：放置するとどう損するか この節では、言い換えを**その行の中の丸括弧で**書く。行に分けて足すと3行に収まらない。 ## 対応方針 `ai-fixable` を付けたときだけ書く（`issue:needs-human-decision` のときはセクションごと省き、「人間に決めてほしいこと」に書く）。別セッションが方針を決め直さず、そのまま着手できる状態を目指す。 **採る案**：何をするかを1文で書く。 **書き先**：「書き先を決める」のどの行に当たるかと、選んだファイルを書く。既存ファイルを選んだなら、**そのファイルの目的・対象範囲を1行引用して並べる**。 | 対象 | いま | 変えた後 | | ---------------------------- | -------------------- | ---------------------- | | `path/to/file.md` の「◯◯」節 | いまの文言を短く引用 | 変更後の文言を短く引用 | **根拠**：なぜその案かを1文で書く。裁定に使ったポリシー・rules があれば名指しする。 **却下した案**：取らないと決めた案と理由を1行ずつ書く（無ければ「なし」）。 文言を書き換える変更は実際の文言を、コードの変更は「いまの振る舞い→変えた後の振る舞い」を書く。変更が複数あるなら行を分け、セルに収まらない長い差分は `<details>` に逃がす。 ## 人間に決めてほしいこと `issue:needs-human-decision` を付けたときだけ書く（`ai-fixable` のときはセクションごと省く）。人間が Issue を開いた瞬間に「何を決めればよいか」が分かる状態を目指す。 **該当する名指し例外**：どれに当たるかを書く（例：不可逆・外部に出る）。 **論点**：人間に何を決めてほしいのかを1文で書く（例：使わなくなった `docs/old/` を消すか残すか）。 | 案 | 利点 | 欠点 | AI の見立て | | --- | ---- | ---- | ------------------- | | 案1 | | | 有力（根拠を1文で） | | 案2 | | | — | ## タスク一覧 実装を完了させるために必要なタスクをチェックボックス形式で列挙する。実装者はこのリストを1つずつ確認し、完了ごとに `gh issue edit` でチェックを更新する（CLAUDE.md の厳守ルール）。設計書・`docs/requirements.md`（要件定義）の更新が必要な場合は、その更新タスクも必ず含めること。 - [ ] タスク1 - [ ] タスク2 ## 完了条件 どうなったら閉じてよいかを書く。タスクの言い換えではなく、**外から観測できる状態**で書く（例：`npm run lint` が通る）。 - [ ] 条件1 ## 現状 下の項目を埋めて書く。**1項目1文**で言い切る。項目は足してよいが、見出し語（対象箇所・確認済み・未確認・却下した案）は変えない。 - **対象箇所**：`path/to/file.ts:42` の `functionName` など、実在するパス・シンボル。書き先がまだ無いなら「未作成」と書き、関係する既存文書を挙げる - **確認済み**：このセッションで確かめた事実 - **未確認**：別セッションが調べ直すべきこと - **却下した案**：取らないと決めた方法と、その理由（無ければ「なし」） 1文に収まらない引用・エラー出力・長い根拠は `<details>` に逃がし、本文には出さない。 <details><summary>根拠（引用・エラー出力）</summary> （ここに転記する） </details> ## 実装フロー（使用するSkill） このIssueを実装する際に使う開発フローSkillを実行順に記載する。**issue番号だけで開発フローを自動追従させるための情報**なので省略しない。変更種別→Skillの対応は CLAUDE.md「開発フロー」が正典。ドキュメント修正のみなど該当Skillが無い場合は「該当なし（直接編集）」と書く。 | 順 | 変更種別 | 使用Skill | | --- | -------------- | ----------- | | 1 | 例：アプリ実装 | `/code-dev` | ## ブロッカー 先に終わっている必要がある Issue を番号で名指しし、何を待つのかを1文で書く。無ければ「なし（すぐ着手できる）」と書き、**節を空にしない**。 - #123 — 何が無いと始められないか 依存と数えるのは「成果物が無いと動かない」「決定が出るまで書き始められない」だけで、同じファイルを触ることは数えない——それは並行作業の調整であって着手順ではない。境界の細かい判定は [`/issue-deps`](../issue-deps/SKILL.md) が持つ。 ## どう気づいたか 問題が見つかるまでの流れを時系列で書く。3〜5項目、1項目1文。別セッションが「なぜこれが問題なのか」を追体験できる状態を目指す。 1. 何の作業をしていたか 2. 何を見て・どのコマンドを実行して、おかしいと思ったか 3. その場で何が起きたか（人間の指摘・エラー出力・見比べの結果） </issue-template> ### 3. 起票前セルフチェック 本文を書いたら、**この会話を知らない自分が読んだつもりで**一度読み返す。満たしていない項目はその場で書き足す（ユーザーへの確認はしない）。 - [ ] いまの作業で自分が編集したファイルの中の不備ではない（判定は「原因が自分か」ではなく編集したパスと一致するか。そのファイル内なら起票を取りやめ、その作業の中で直す） - [ ] 「この変更が必要な理由」「対応方針」「タスク一覧」の3節だけを読んで、何をするか分かる - [ ] 「この変更が必要な理由」が1文1行の3行で、2行目に実際に起きたことが1つ入っている - [ ] 会話依存の指示語が残っていない - [ ] 対象箇所が実在するパス・シンボルで名指しされている（書き先がまだ無いなら「未作成」と書いた） - [ ] 「書き先を決める」を上から当てて書き先を決めた（「既存ファイルがこれしか無いから」で選んでいない）。決まったなら「対応方針」の**書き先**に、まだ無いなら「人間に決めてほしいこと」の名指し例外に、その旨を書いた - [ ] 書き先に既存ファイルを選んだなら、そのファイルの目的・対象範囲を1行引用して並べ、書こうとしている内容がその範囲に入っている - [ ] 「現状」の見出し語が対象箇所・確認済み・未確認・却下した案のままで、4項目とも埋まっている - [ ] 「実装フロー（使用するSkill）」が埋まっている - [ ] 「ブロッカー」に、先に終わっている必要がある Issue を番号で書いた（無ければ「なし（すぐ着手できる）」と書いた） - [ ] 既存 Issue と重複しないか `gh issue list --state all --search "<タイトルの主要語>"` で確認した（`--state all` を外すと open だけを見ることになり、**却下済み（NOT_PLANNED）の同じ提案を再起票する**） - [ ] 該当するポリシー・rules を探した（見つからなければ `policy-gap` を付けた） - [ ] 見つかったポリシー・rules と「タスク一覧」「完了条件」を照合し、反する作業を指示していない（反していたらタスク側を直した） - [ ] `ai-fixable` / `issue:needs-human-decision` のどちらか一方を決めた - [ ] `issue:needs-human-decision` を付けたなら、名指し例外のどれに当たるかを言えて、「人間に決めてほしいこと」に論点と選択肢を書いた - [ ] `ai-fixable` を付けたなら「対応方針」に採る案・「いま→変えた後」の対比・根拠・却下案を書き、対比には実際の文言（またはふるまい）を引用した - [ ] Issueの階層ガイドの「主に触るもの」表のどの行に当たるかを言えて、親にするフェーズ（または「親を付けない」）を決めた ### 4. 起票 `gh issue create` を1コマンドで実行する。本文はヒアドキュメント or `--body-file` で渡す。 ```bash gh issue create \ --title "<タイトル>" \ --assignee @me \ --label boy-scout,<ai-fixable|issue:needs-human-decision>[,policy-gap] \ --body "$(cat <<'EOF' （テンプレートの全セクションを埋めた本文） EOF )" ``` - ラベル未作成でコマンドが失敗したら、`gh label create <名前> --description "<「付与するラベル」表の付与条件>"` で作ってから同じコマンドを再実行する。事前確認はしない（毎回の `gh label list` は速さを損なうため、失敗したときだけ払う）。 ### 5. 親に紐づける 親は[Issueの階層ガイド](../../../docs/guide/issue-hierarchy.md)の「主に触るもの」表で決める。**この Issue が主に触るものが `.claude/` 配下・`docs/policy/`・`docs/design/`・`docs/guide/` なら、親を付けない。** ハーネス・ポリシー・設計書の手直しは開発フローのどのフェーズの作業でもないからで、本スキルの起票はこれが最も多い。 それ以外は表のフェーズIssueの sub-issue にする。フェーズIssueは `phase` ラベルで引く。同じフェーズ名が複数あれば**いちばん番号が大きいもの**を使う。 ```bash gh issue list --label phase --state open --json number,title,id gh api graphql -f query='mutation($parent:ID!,$childUrl:String!){addSubIssue(input:{issueId:$parent,subIssueUrl:$childUrl}){subIssue{number}}}' \ -F parent="<親のnode ID>" -F childUrl="<子のURL>" ``` 紐付けに失敗しても、**起票そのものは成功している**。失敗したら親が付かなかったことを伝えて続行し、起票をやり直さない（同じ Issue を二重に立てることになる）。上限100件で失敗したときは、階層ガイドの世代交代の手順に従う。 起票した Issue の**番号と URL**（親を付けたならその番号も）を提示して完了とする。 ## 使用方法 ``` /quick-issue <起票したい内容> ``` 例： ``` /quick-issue ログイン失敗時のエラーメッセージが英語のままなので日本語化したい ```