菜单
issue 対応の 10 ステップ・ループ (Step 0-pre shift-left 調査 → 設計 → 実装 → 敵対的レビュー → メタレビュー → E2E → merge → 振り返り) を駆動する汎用 dev process skill。issue 番号 or URL を渡して起動する。Use when the user asks to run the issue loop / 10 ステップループ for a GitHub issue, or to 対応 an issue with the full review process.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | issue-loop |
| description | issue 対応の 10 ステップ・ループ (Step 0-pre shift-left 調査 → 設計 → 実装 → 敵対的レビュー → メタレビュー → E2E → merge → 振り返り) を駆動する汎用 dev process skill。issue 番号 or URL を渡して起動する。Use when the user asks to run the issue loop / 10 ステップループ for a GitHub issue, or to 対応 an issue with the full review process. |
| user-invocable | true |
| disable-model-invocation | false |
GitHub issue 1 件を、shift-left 調査から振り返りまでの 10 ステップで対応するプロジェクト非依存の dev process。品質担保の核は (1) 設計前の独立インパクト調査、(2) 実装とレビューの文脈分離 (クリーンなサブエージェント)、(3) レビュー finding の独立検証 (メタレビュー)、(4) 振り返りによるチェックリストへのフィードバック。
issue 番号 or issue URL。省略された場合は対象 issue を確認してから開始する。
claude-opus-5) サブエージェント。メイン loop (主担当) の仮説・文脈を持ち込ませないことで、確証バイアスを避ける。メイン loop が自律で下してよいのは技術判断まで。以下の 3 点はユーザー (プロダクトオーナー) の判断領域であり、自律実行の明示的な許可 (「確認なしで進めて」等) がない限り、質問ツール等で確認してから先へ進む:
確認時は、判断に必要な文脈 (選択肢 / 推奨 / 影響範囲) を質問自体に含め、ユーザーが過去ログをスクロールバックせずに答えられる形にする。確認待ちの間、ブロックされない他 Step の準備 (レビュー brief の生成等) は進めてよい。
処理は fix / 別 issue / accept / 起票しない の 4 値。どれを選ぶかの前に、この 1 問に答える。
この finding を、通常の使い方をしている外部ユーザーが踏むか？
| 答え | 処理 |
|---|---|
| A. 踏む — 文書どおりの手順・普通のリポジトリで発現する | 起票する。criticality:major。 ユーザーが最初に見る症状を 1 文で書く |
| B. 特殊な入力/設定なら踏む — CRLF / BOM / symlink / 非英語 / ID 衝突 / 特殊な markdown 形状など | 既存 issue を検索し、同じ root cause があればそこにコメント。無ければ起票して criticality:minor。 トリガを 1 文で書く |
| C. このリポジトリの開発しか困らない — dogfood / 自前 CI / 自前 skill / 自前 spec | 起票しない。 ループの報告に 1 行残す |
| D. 挙動の欠陥ではない — docs 不整合 / リファクタ / 「どちらが正しいか決めたい」 | 起票しない。 「決めたい」ものはそのループ内で決めるか、ユーザーに 1 問聞く |
なぜ上限が要るか (2026-08-01、全 238 issue / 41 日分の実測):
同時に、その時点の open 61 件のうち通常利用で踏むものは 6 件 (9.8%)、挙動の欠陥ですらないものが 24 件 (39%)、うち約 11 件は既に修正済み・重複・非欠陥だった。増えていたのは欠陥ではなく観測で、それを止める規則が 1 つも無かった。
対象プロジェクトの AGENTS.md / CLAUDE.md に Step 0-pre 用のプロジェクト固有チェックリスト skill が定義されていればそれに従う (例: artgraph の artgraph-graph-primitive-impact)。無ければ以下の汎用チェックを brief にする:
action / status 種別等) を新設・拡張する場合、上記の「実際の状態が既存の値に丸め込まれていないか」に加え、逆方向 — 型・switch 等の消費側に列挙された variant のうち、生成側のどの入力パスからも到達不能な variant がないか — を、生成側コードと突き合わせて確認する。到達不能 variant は tsc の網羅性チェックが与える「ハンドリング済」保証を空証文化させ、JSON 消費側の誤解を誘発する (PR #367 LOW-4: 型定義と switch case には存在するが生成側は produce しない "skipped-not-selected" variant が残り、--format json 消費側が「非選択 agent はこの action で出てくる」と誤解しうる状態だった)|| true や pipefail との相互作用に注意)、(b) 検出パターン・発火条件が大文字小文字・区切り文字・等価表記 (別綴りの同値アドレス等)・縮退値 (空文字・型違い — 配列を期待する入力への裸文字列等。従来無検証だったフィールドを新設コードが最初に消費する場合、その検証状態を先に確認する: PR #359 H1) に耐えるかを意図的なすり抜けサンプルの実測で確認し、(c) 同じ入力面の兄弟パラメータに同等の検証を付けたか (片側だけ厳格化すると、無検証側の縮退値が新設の警告条件そのものを素通りする) を横比較し、(d) 既存 fail-closed ガードを緩和する変更では、まず「実際に何が現在のパターンにマッチしていたか」を列挙し (git ls-files | grep -iE '<FORBIDDEN>' 等)、パターン/ルールそのものを削除・緩和するのではなく、対象だけを狙った最小スコープの例外 (pathspec 除外・許可リスト追加・narrow patterns 等) で対応しているかを確認する (PR #367 HIGH-1: SC-007 の \.codex/hooks は commit された対象 0 件・kiro.*hook は 1 テンプレのみで、パターン全削除ではなく pathspec 除外で足りたのに全削除して将来同種違反への保護を永続的に失わせるところだった)brief テンプレ (Step 0-pre) あなたは {{repo}} の調査担当です。issue {{issue}} で
{{変更対象}}を{{変更の一行要約}}する変更を検討しています。実装はまだ存在しません。{{チェックリスト skill のパス or 上記汎用 4 チェック}} を順に実行し、「この変更で SILENT に破壊される経路」のランク付きリスト (HIGH/MEDIUM/LOW) を報告してください。各項目: (a) 経路 (b) 影響を受ける機能 (c) 該当テストの有無 — その経路を単体でカバーするテストと、他経路との組み合わせ (交差点) をカバーするテストを区別して報告する。マトリクスの交差セル (例: 「CLI 出力フォーマット × 複数エージェント混在」) は前者があっても後者がなければ後者は明示的に「なし」と書く (PR #367 MEDIUM-3: dispatch データ層と CLI 単一エージェントは各々 cover 済だが、両者の交差セルは未 cover でランタイム regression 検知不能だった) (d) 推奨 (本 PR で fix / 別 issue / accept)。「別 issue」を選ぶ前に起票ゲート (A/B/C/D) を通し、選んだ答えを併記すること。
Step 0-pre で確立した事実が下流の Step で減衰する形の欠陥は、レビューで「既存チェックを正しく回せば出たはず」に分類されるものの大半を占める。チェックリストの不足ではなく申し送りの問題なので、報告の末尾に以下 2 表を必須で置き、Step 1 が各行に自分の判断を書いてから実装へ進む。
(1) 名指し箇所 × 4 値処理表 — ファイル:行 / 事実 / 起票ゲート (A/B/C/D) / 本 PR で fix・別 issue・accept・起票しない。Step 0-pre が行番号付きで名指しした箇所を全件。Step 1 はこの表を逐語で引き継ぎ、各行に判断を書く。「確認する」はどの値でもないので不可とする (動詞を弱めた瞬間に実装段階で「確認のみ」で終わり、レビューで再指摘される)。Step 2 は表の全行に結果を書く。
(2) 測定 × 対象案 × 転写可否表 — 測定内容 / 対象案 (候補 A / 候補 B / HEAD) / 結果 / 採用案でも成立するか (成立する・要再測・無関係)。調査段階で棄却した案について取った測定は、採用案へ自動的には引き継がれない。 Step 1 はこの表の「要再測」行を実装前タスクとして引き継ぐ。
前例: PR #423 (issue #387) — Step 0-pre が棄却した候補について「--diff 系ゲートは baseline を同一バイナリで再スキャンするので意味論変更は両側に効き、失われた signal は gate に出ない」を exit code 込みで実測していた。この性質は案に依存しないのに、採用した候補の設計文書が「この方向は fail-loud」と無限定に断定し、その文言が upgrade note まで到達した。表 (2) があれば Step 1 の断定と正面衝突していた。
Step 0-pre の report を入力に、実装方針を決める。report の HIGH 項目は設計で必ず言及 (対処 or accept の理由) する。設計候補が複数あり trade-off が非自明な場合、および spec/プロダクト意図の変更を伴う場合は、決める前にユーザーに確認する (上記「ユーザー判断のエスカレーション」1/2)。
タスク分解 + 7 観点セルフチェック (Step 4 と同じ観点で自分の計画を先に叩く): 境界条件 / 条件分岐の組み合わせ / 不正な状態遷移 / 例外系 / 実運用の事故 / エッジケース / 考慮漏れ。
新しい失敗/劣化シグナル (exit code・reject 経路等) を導入する計画では、既存の類似 sibling コマンド群の対応する契約を表にし、一致させるか意図的に変えるかの方針を brief に明記してから実装委譲する (単一コマンドの視点では正しく見える設計が、横比較で初めて非一貫と分かるパターンの防止)。この表の粒度は**コマンド単位でなく「コマンド × early-exit 経路」**まで下げる — 横断的不変条件 (「この条件はあらゆる早期 exit を覆う」型) を新設する計画では、sibling コマンドの既存 early-exit 経路にも同じ不変条件を適用するかを明示する (PR #353 L1: impact に導入した「resourceExhausted は全早期 exit を覆う」パターンが、お手本側 check の既存 early-exit 2 箇所に未適用のまま残った)。
重複計算を single-source 化する計画では、残存する duplicate 呼び出し箇所を全列挙し、削除するか「不整合検出の防御」を付けるかを明記する (PR #353 H2: ingest を scan() に統一した後も残した事前プローブが、統一先と食い違ったとき silent に結果キーが消える TOCTOU になった)。
「ある実行時挙動が起きるか」を判定する新設チェック (設定の有効性判定・保護の有無検査等) は、その挙動を実際に生む本物の評価器 (glob matcher / parser / resolver 等) を合成入力で呼ぶ設計を第一候補にし、文字列形状からの推定 (substring/segment 判定) は避ける (PR #359 H2: 文字列 heuristic は「機能しない除外を保護ありと誤判定」「機能する除外を保護なしと誤判定して実リークを完全沈黙で見逃す」の両方向に破れた。実評価器は既存依存に含まれていることが多く、切り替えコストは低い)。
既存 fail-closed ガード (CI regression guard / lint 禁則 / 許可リスト等) を緩和する計画では、着手前にまず現行パターンで「実際に何が commit 済で違反していたか」を実測し (git ls-files | grep -iE '<FORBIDDEN>' 等)、その結果を設計に織り込む — 実測せずに広く緩和すると、Step 4 レビューで「削除ではなく最小スコープ例外で足りた」と narrow 化を求められる往復コストが発生する (PR #367 HIGH-1: SC-007 の \.codex/hooks は commit 対象 0 件、kiro.*hook は 1 テンプレのみだったが、実測せずパターン全削除で先行し Step 4 で pathspec 除外への narrow を強いられた)。上記の Step 0-pre チェック 8(d) の裏返し — Step 0-pre は緩和の粒度を診断するチェック、Step 1 はその診断結果を設計に織り込む段階。
brief テンプレ (Step 2) あなたは {{repo}} の実装担当です。issue {{issue}} の実装計画は以下です: {{Step 1 の計画}}。対象ファイル: {{files}}。計画に従い実装し、テストを追加・更新してください。計画にない設計変更が必要になった場合は実装せず報告してください。
brief 作成時の仕様網羅性チェック (Step 0-pre では原理的に検出できない「まだ存在しないコード」の欠陥は、brief の仕様精度で防ぐ):
--force, --strict, --all 等) の意味論を複数 writer/format/経路で対称化する」設計判断が確定した場合、その不変条件 (「全 format で --force は既存ファイルを上書きしない」等) を 1 文の断定形で brief に逐語添付する (「全て対称です」等の要約でなく)。実装エージェントが CLI メッセージ・ドキュメント文字列・エラー remediation を書く際にこの不変条件を手元に持っていれば、"--force" で上書きされるかのような誤誘導文言を自分で弾ける (PR #367 LOW-5: Kiro conflict remediation が "...re-run with --force to let artgraph write its own"と--forceで上書きされるかのような誤誘導になり、file-per-hook writer は--force` を参照しない不変条件と食い違った)。?? フォールバック経路が未検証だった)。テストの実行条件を変える変更 — it() → beforeAll/beforeEach への移動、describe 本体 → hook、別 suite / 別 config への移動、pool / fileParallelism / retry / env の変更 — は、以下を実行する。ローカルと CI で負荷条件が違うために片方でだけ落ちるクラスを、ループの他のどの段も構造的に拾えない (Step 7 の E2E は実機 CLI を見るのでテストスイートの実行条件を見ない)。
「CI と同じコマンドを回せ」では捕まらない。 判別要因はコマンドではなくランナーの負荷であることが実測されている — ローカルで CI と同一コマンドをコールドキャッシュで回しても全 pass、別 OS の CI job も同じコマンドで pass、という形で片側だけが落ちる。捕まえられるのは静的な問いだけ:
移動先が継承する既定値を config ファイルから読み取る。
grep -n 'testTimeout\|hookTimeout\|retry\|pool\|fileParallelism\|env' vitest*.config.ts
config が設定している軸と、設定せず runner の既定に任せている軸を区別する。 未設定の軸へ管轄が移ると budget が黙って縮む。
姉妹 config に同じ罠の記録がないか grep する。
git grep -n 'Timeout\|timeout' -- vitest.e2e.config.ts vitest.perf.config.ts
所要時間にローカル単体実行の値を使わない。同じ作業をしている既存テストの CI 実測値を使う。 CI ログの per-file 行 (tests/x.test.ts (N tests) NNNNms) がそれ。
budget ≥ 4 × CI 実測でなければ明示引数を置く (beforeAll(fn, 120_000))。明示引数は config / CLI の値を上書きするので、config を直すより局所的で安全。
判定オラクル (スイープ): pnpm exec vitest run --hookTimeout=<CI 実測の 1.2 倍>。落ちたファイルが「既定に頼っていて実際に遅い hook」。明示引数を置いた後は落ちない。
重い作業は hook より it() に置く方を既定にする。 config が curate している軸に乗るため。hook に置く理由 (collection 時 throw を防ぐ、複数 it() で共有する) があるときだけ hook にし、そのとき step 4 の明示引数を必ず付ける。
前例: PR #423 (issue #387) — Step 6 がレビュー指摘の正しい修正として buildGraph(REPO_ROOT) を describe 本体から beforeAll へ移した瞬間、config が curate している軸 (testTimeout: 30000) から curate していない軸 (hookTimeout 未設定 → vitest 既定の 10s) へ管轄が移り、budget が 30s → 10s に縮んだ。ローカル単体実行 2.5s に対し CI (ubuntu) は 12.1s で、Hook timed out in 10000ms が ubuntu の job だけで発生し macOS job は緑だった。同じ罠の記録が vitest.e2e.config.ts に前の PR 由来で逐語であり、同種テストの CI 実測値 12.1s は、落ちた CI ジョブのログの中にそのまま印字されていた。修正後のツリーで step 5 のスイープを --hookTimeout=300 まで振っても 124 ファイル全 pass = このスイープはノイズを出さない。
メイン loop が diff を確認し、プロジェクトの規約 (commit 規約 / PR テンプレ / CI ゲート) に従って PR を作る。実装報告の定量主張 (「件数は 0→0 で不変」等) を PR 本文に載せる場合、集計粒度を 1 段変えた再計測 (テスト単位→生ペア単位等) で裏取りしてから載せる — 粗い粒度の「不変」は細かい粒度の大変化 (PR #363 M1: dogfood テスト 0→0 の裏で生ペア 1140→605) を覆い隠し、レビュアーが信頼する数値として独り歩きする。Step 2 実装エージェントの報告に「逸脱」「関連 follow-up」等のフラグがあれば、PR 作成前にメイン loop が直ちに triage し、起票ゲートを通した上で fix now / 別 issue 化 / accept / 起票しない のいずれかを明示する。silent に次 Step へ進めない (検出済みの情報が orchestration 側で握りつぶされるのを防ぐ)。
triage で「fix now」を選んだ項目は、orchestrator が自分で書かない。 Step 2 と同じ形式の brief (対象ファイル / 変更内容 / 該当するセルフチェック項目) を作ってクリーンなサブエージェントに出す。委譲が割に合わない小ささなら、その差分に対して発火するチェックだけを orchestrator が明示的に実行し、実行したチェック番号と結果を PR 本文に書く。
orchestrator 自身が書いた差分は、Step 2 brief のセルフチェック群を 1 つも通らずに PR へ着地する — この経路はループの構造上、レビュー以外のどの層にも捕捉されない。1 行の修正でも、それが「認識規則の受理集合を変える」なら消費者の全数列挙が、「新しい正当化コメント / 断定文を書く」なら反例探索が、「テストを追加する」なら判別オラクルの明記が発火する。
判定オラクル: fix now で入れた差分について「この変更単独で Step 0-pre のどのチェックが発火するか」を 1 行で答えられること。答えが「なし」なら本当に無害。
前例: PR #429 (issue #422) — Step 2 が「認識と書き換えが ATX closing sequence で乖離する。候補修正は 1 行だが計画外なので実装しない」と正しく報告し、orchestrator が Step 3 でその 1 行を自分で入れた。消費者を全数列挙していれば git grep -n '(#+' -- src の 5 行に specDefinitionId が出ていた (実測)。結果、rename --merge が exit 0 で成功を報告しながら spec を半適用し、直後に check --gate が 0→2 になる回帰をその PR 自身が持ち込んだ。同時に添えたテストコメントの「the two sides can disagree here and nowhere else」も実測 12 形状で偽だった。
「全 N 箇所」「他に無い」型の完全性主張を PR 本文・issue・コードコメントに載せる場合、その根拠の横断 grep は NUL バイト入りファイルを無言で除外しないツールで実行する — ripgrep および ripgrep 実装の検索ツールは -l / -c の一覧・件数モードでも既定でバイナリ判定したファイルを結果から落とし、stdout・stderr・exit code のどこにも痕跡を残さない。grep -a / git grep を使うこと。この失敗モードは「検索がヒット 0 件」ではなく「検索対象からファイルごと消える」ため、件数が減ったことに気づく手掛かりが原理的に存在しない (前例: PR #390 が「lastIndexOf は 5 箇所」と書いたが真値は 6 ファイル 7 箇所。無言で落ちた 2 ファイルの片方はその PR 自身が編集していたファイルだった。同種の見落としは PR #376 でも発生しており、「注意する」型の対策では 2 回とも防げていない)。
別のクリーンな Opus 5 に、実装文脈なしで PR diff だけを渡す。
brief テンプレ (Step 4) あなたは {{repo}} の敵対的レビュアーです。PR {{pr}} の diff を、以下の 7 観点で「壊す」つもりでレビューしてください: (1) 境界条件 (2) 条件分岐の組み合わせ (3) 不正な状態遷移 (4) 例外系 (5) 実運用の事故 (6) エッジケース (7) 考慮漏れ。各 finding にランク (HIGH/MEDIUM/LOW) と再現手順を付けること。褒める必要はありません。
さらに別のクリーンな Opus 5 が Step 4 の findings を独立検証する。単なる検証にとどめず、レビューアが生産的だった seam の second-look (横展開探索) を brief に含める — 同じ seam の兄弟箇所に同型欠陥がないかを探索させる。
brief テンプレ (Step 5) あなたは {{repo}} のメタレビュアーです。PR {{pr}} に対する以下のレビュー findings を独立に検証し、各 finding を 妥当 / 誤検知 / 要追加調査 に分類してください: {{Step 4 findings}}。加えて、妥当な finding が出た seam (同一ファイル・同一パターンの箇所) について、同型の欠陥が他に残っていないか横展開で探索してください。
クリーンな Opus 5 に、Step 5 で妥当と判定された findings のみを渡して修正させる。修正指示の brief には、上記「テスト実行条件の継承監査」を Step 2 と同じくセルフチェックとして含める — 正しい修正が副作用でブロッカーを持ち込む経路がここに集中する。
Step 6 が Step 4/5 の測定をやり直して反する結論を出す場合、(a) 使った入力の逐語バイト列を並べて Step 4/5 のものと同一であることを先に示す、(b) 異なるなら「別形状の測定であって訂正ではない」と明記する、(c) 件数が動いた場合は測定範囲 (対象ファイル集合) を併記する。 段間の「訂正」は、実際には別の対象を測っているだけのことが多い (前例: 6 形のうち 2 形を「再現しない」とした訂正は両方とも別 fixture を測っていた / conjunct mutation の「20 件」と「68 件」の差は測定範囲がサブシステム限定かフルスイートかの違いだった)。誤った訂正がそのまま issue の authoritative な NOTE として公開された実例がある。
Step 6 の修正が (a) テストを別の実行文脈へ移す、(b) config / 環境変数を触る、(c) 新しい I/O を導入する のいずれかを含む場合、Step 7 へ進む前に push して CI を 1 回通す。 Step 7 の実機確認は数十分かかるので、その前に数分の CI で潰せるものは潰す。判定は「テスト実行条件の継承監査」step 1 の grep 1 本でつく。
クリーンな Opus 5 が、テストではなく実際の入口 (CLI / アプリ / API) から変更後の挙動を確認する。ここで新 finding が出たら Step 4 相当として扱い Step 5 に回す。
修正を push し、CI green を確認して main へ merge する。merge の実行直前にユーザーに確認する (上記「ユーザー判断のエスカレーション」3)。
issue-retro skill を起動する (対象: 本 loop の PR と各 Step の findings)。「Step 4/5/7 が見つけた finding のうち Step 0-pre で検出できたはずのもの」を特定し、プロジェクト側チェックリスト skill への追加を提案する。
docs-only など明白に低リスクな変更では Step 0-pre / Step 5 / Step 7 を省略してよい。ただし省略した Step は出力に「skipped (理由)」と明記し、silent skip にしない。
artgraph コントリビュータ向け内部 skill。グラフ基本操作 (src/graph/traverse.ts / src/graph/builder.ts の BFS・エッジ意味論・ID 解決) や graph-core 関数 (impact() / check() / buildGraph()) を変更する issue/PR に着手する前 (Step 0-pre) に、24 チェックの shift-left インパクト調査を実行し「silent に破壊される経路」のランク付きリストを報告する。Use when starting a PR that touches src/graph/, edge semantics, or graph-core function signatures/return values.
Performs a safe rename / split / merge of requirement IDs across spec, code, tests, and lock. Use when the user asks to rename a REQ ID, split one ID into multiple, or merge multiple IDs into one. Make sure to use this skill whenever requirement IDs are being restructured.
issue-loop の Step 9 (振り返り) 単体 skill。対象 PR のレビュー/メタレビュー/E2E findings を「事前 (Step 0-pre) に検出可能だったか」で分類し、プロジェクト側チェックリスト skill への追加提案を出力する。Use when the user asks for a retrospective of a completed PR / issue loop, or to feed findings back into a Step 0-pre checklist.
Runs `artgraph impact` to surface which requirements, docs, and files a proposed file or symbol edit touches (forward: files/symbols → REQs). Use when the user explicitly names file paths or `path:symbol` pairs, or wants the impact of files staged in `git diff`.
Detects implicit impacts: REQs reached by tasks.md `Files:` but not mentioned in `tasks.md` / `plan.md` / `spec.md` (reverse audit). Use after editing tasks.md / plan.md (e.g. after `/speckit-tasks`, or after updating `.kiro/specs/<name>/tasks.md`), before implementation.
Installs artgraph in the current project, detects the package manager (npm / pnpm / Bun / Deno; default and Yarn fallback are pnpm), and wires up Skills, hooks, agent-context snippet, and any detected SDD-tool integration. Use when the user asks to install / set up / add artgraph, asks whether artgraph is set up or what is installed, or wants to wire artgraph into an SDD tool (Spec Kit / Kiro) added after artgraph. Make sure to use this skill whenever the user mentions artgraph for the first time and `artgraph` CLI is not yet available.