start-issue

name	start-issue
description	GitHub issue から作業を開始するときに使用。実装の前段階（ブランチ作成・調査・計画・計画レビュー）までを行う。
disable-model-invocation	true
argument-hint	<issue-number>
allowed-tools	["Bash(git *)","Bash(gh *)","Read","Write","Grep","Glob","Skill"]

Issue #$ARGUMENTS の作業を開始する。実装判断は自律的に行い、要求判断が必要な場合のみ確認する（後述）。

Step 1 — ISSUE 読み込み & 要求の曖昧さ判定

gh issue view $ARGUMENTS

issue の内容（タイトル・本文・ラベル・コメント）を把握し、要求が一意に解釈できるか判定する:

• 実装の曖昧さ（「どう作るか」が不明）→ コードとドキュメントから解決できる → そのまま進む
• 要求の曖昧さ（「何を作るか」が不明）→ コードをいくら読んでも答えが出ない → 質問してから進む

要求の曖昧さがある場合、最も影響の大きい1〜2点に絞って質問する。例:

• UI の見た目・操作フロー
• 既存動作を変えるのか、追加するのか
• 対象範囲（全項目か、特定条件のみか）

回答を得てから Step 2 に進む。

Step 2 — main 最新化 & ブランチ作成

以下を順に実行する:

git checkout main

git pull --ff-only

issue の内容から適切なブランチ名を決める:

• 機能追加: feat/<短い説明>
• バグ修正: fix/<短い説明>
• その他: chore/<短い説明>

git checkout -b <branch-name>

Step 3 — 調査と分析（workspace/research.md）

workspace/research.md・workspace/plan.md・workspace/plan-review/（ディレクトリごと。/plan-review「Step 2 — 並列サブエージェントで検証」のスカウトと「Step 2b — 独立導出 + 差分（常に実施・盲点クラスの漏れ検出）」の成果物。ファイル名が毎回変わるため列挙せず、新鮮性は「上書き」ではなく /plan-review Step 2 が起動前に行う削除が保証する——上書きは書き手が落ちた回には起きない）が既に存在する場合は上書きする（前回の作業成果物）。このサイクルで書き直すファイルはここに列挙されたものだけである——列挙から漏れたものは前サイクルの内容のまま残り、次に読む人が今回の成果物と誤読する（workspace/measurement.md が #628 のまま取り残されている実例がある）。

SPEC.md、関連する CLAUDE.md、ソースコードを読み、issue の要求を分析する。

workspace/research.md に以下を出力:

• issue の要約: 何を解決/実現するか
• 関連コード: 影響を受けるファイル・モジュール・関数の列挙
• 既存パターン: 類似の実装が既にあるか、再利用できるか
• 技術的制約: Win32 依存、IPC 境界、リアクティブ制約など。Win32 API を使う場合、SendInput/SetForegroundWindow/ShowWindow 等の入力・ウィンドウ系 API は部分的に非同期な場合がある。計画時に MSDN で同期性を確認し、技術的制約に記録する
• 未解決の疑問: 調査で判明しなかった点（あれば）

列挙の事実確認: 「関連コード」に挙げたファイル・関数が実在し、説明が正確かを grep で確認してから Step 4 へ進む。研究の前提誤りは plan へ伝播する——/plan-review「Step 2b」 の独立再導出が伝播後に拾うが、前提はここで正すのが最も安い。

外部ソースが根拠のときの追加確認（外部 issue・上流バグ・外部仕様を根本原因の根拠にする場合のみ発火。使わない issue では不要）: issue 本文冒頭の説明を確定事実とせず、timeline を最終 maintainer 回答まで辿って現在の結論（fixed / reverted / 未修正）を掴んでから前提として扱う。上流の記述とローカル実装（使用中バージョン・設定者→中間層→実 consumer の実行経路）が食い違うときは、どちらを採用したかを理由付きで research.md に記す。上の実在確認が内部前提を、/plan-review「Step 2b」 がコードベースを覆うのに対し、外部の事実だけはどの下流検査も再導出できない——ここで正さなければ後段で拾えない（#565。内部前提=能力・根本原因診断の裏取りは docs/development-principles.md「デバッグ・バグ修正」節）。

Step 4 — 実装計画（workspace/plan.md）

workspace/research.md の分析結果をもとに、workspace/plan.md に実装計画を作成する。

計画には以下を含める:

• 変更ファイル一覧: 各ファイルで何を変更するか
• 実装順序: 依存関係を考慮したフェーズ分け
• 不変条件: 各変更が守るべき不変条件。新たな状態フラグ・プロセス・ウィンドウ・リソースを導入する場合は「失敗・異常終了・予期しない順序で呼ばれたときにどうなるか」も含めて記述する
• テスト方針: 追加・更新するテストと検証コマンド
• SPEC.md 更新要否: 挙動変更を伴う場合は更新内容を記載

docs/development-principles.md の開発原則（KISS/DRY/YAGNI）と AGENTS.md「開発ワークフロー」の実装着手前（判定・要件確定・影響範囲・事前調査）に従うこと。

Step 5 — セルフレビュー & 計画更新

5a. check スキルによる計画検証

計画の内容に応じて該当する check スキルを実行し、計画の見落としを検出する。発見事項があれば計画を更新する。

• /plan-review は常に実行する（サブエージェントで影響範囲・不変条件・スコープを並列検証）。
• ほかの check スキルは、AGENTS.md「条件別チェック（トリガー → 参照先）」表に従って選ぶ（トリガー→検査の写像の SSOT はその表。二重管理を避けるためここに再掲しない）。判定対象は計画が記述する設計上の操作であって、既存コードの grep 結果ではない。

5b. セルフレビュー（plan-review 固有の補完）

Step 5a の /plan-review が ①対称コードパス ②影響範囲の網羅性（呼び出し元 grep）③リソース管理（生成/破棄ペア・false に戻さない AtomicBool／unlisten の無い listen()／kill の無い子プロセス）④既存パターンとの整合 ⑤YAGNI を検証済みである（/plan-review「Step 2」の観点＋ /plan-review「Step 2b」の独立再導出）。5b でこれらを再実行しない——同一 plan.md への二度手間を避ける。plan-review の「要対処」を確認し、あれば workspace/plan.md を更新する。

ただしこの免除は、plan-review が「独立レビュー不成立」と報告したエントリには及ばない——そのレイヤーの ①〜⑤ は検証されていない。5b で自ら確認する（/plan-review の再実行は workspace/plan-review/ を作り直すため、届いていた他エントリの成果物も消える——当該レイヤーだけを 5b で見る方が安い）。不成立が残るならその事実と代替検証を workspace/plan.md 末尾の「セルフレビュー」セクションに記す（本ファイル末尾の引き渡し契約「レビュー済みの計画」が偽になるのを防ぐ）。

5b では plan-review が扱わない次の3観点だけを追加で確認し、問題があれば計画を修正する:

1. 境界条件: エッジケースの検証ケースが計画に含まれているか（境界を列挙し最低1件ずつ・AGENTS.md「事前調査（レビュー未然防止）」）
2. シンプル化の挑戦: 「この設計、本当にこの複雑さが必要か」— 新たな状態（AtomicBool・Mutex・子プロセス等）・汎用インターフェース・暗黙の前提を導入する箇所について、より単純な代替がないか問い直す。「この操作が失敗したらどうなるか」を設計段階で書けているか
3. 破壊不変条件 + 検知手段: この変更で「壊れたら即アウト」なシステム不変条件を列挙し、検知手段（テスト・スモーク・手動確認手順）とセットで plan.md に記述したか。特に Win32 フック・ホットキー・プロセス間通信など「戻ってこない」系のリスク。plan-review は「失敗時どうなるか」までは見るが、検知手段の有無はここで確認する

plan-review の結果（要対処の解消）と 5b の3観点を、workspace/plan.md 末尾の「セルフレビュー」セクションに記録する。

Step 6 — workspace をコミット & プッシュ

セッション断絶・別マシン継続に備え、workspace/ を必ずコミットしてプッシュする。以下を順に実行する:

git add workspace/

git commit -m "chore: workspace 調査・計画 (issue #$ARGUMENTS)"

git push -u origin HEAD

出力

最後に以下を報告:

1. issue の要約（1〜2行）
2. 作成したブランチ名
3. 計画の概要（変更ファイル数・フェーズ数）
4. セルフレビューで修正した点（あれば）
5. 次のアクション: /implement で実装に進めること

引き渡し契約: ここで渡す workspace/plan.md は /plan-review を通したレビュー済みの計画である。/implement はこの前提で計画を読み、調査をやり直さない。計画を検証せずに渡してはならない——検証水準が入口によって変わると、/implement 側が前提を立てられなくなる。