plan

name	plan
description	research の結果と受け入れ条件をもとに、実装方法を選択し TDD ベースの実装計画と動作確認チェックリストを作成する。
allowed-tools	Bash, Read, Glob, Grep, Write, Edit, AskUserQuestion

GitHub issue ( $ARGUMENTS ) から実装計画と動作確認チェックリストを作成する。

本スキルは 意思決定 + 計画策定 に責務を持つ。/research が列挙した候補から実装方法を選択し、受け入れ条件をタスクにマッピングして TDD で計画化し、AC を検証可能にする動作確認チェックリストまで作成する(チェックリストを計画段階で作ることで、/review-plan が実装前にカバレッジを検証できる)。

引数

$ARGUMENTS は <issue> [mode] の形式で受け取る。

• <issue>: issue 番号(123、#123)または URL
• [mode]: auto / normal。auto の場合、本スキル内ではユーザーに質問せず、選択・判断はすべて推奨案で自動決定して、その選択理由と置いた仮定を plan.md に明記する。省略時は normal 相当(質問する)

手順

1. プロジェクト固有の注意点を読み込む

このスキルのディレクトリにある config.json を読み込み、attentions 配列に記載されたプロジェクト固有の注意点(副作用カスケード、暗黙の必須セット、フレームワーク特有のエントリポイント、過去の手戻り事例など)を把握する。以降の計画策定で該当する変更が含まれる場合、対応する波及範囲を計画に反映する。

2. 既存成果物の読み込み

tmp/issues/<issue番号>/ 配下の以下を確認し、存在すればインプットとして活用する。

• research.md(md が無ければ research.html。以降も同様): 受け入れ条件・影響範囲・実装方法の候補・リファレンス・盲点候補(必須相当。なければ step 3 で警告)
• plan.md / checklist.html: 既存の計画とチェックリスト(再計画モード: テスト失敗等で再実行された場合は、新規作成ではなく既存内容を更新する)
• implementation-notes.md: 再計画モードの場合、実装中に記録された逸脱(Deviations)を計画へ反映する

3. 受け入れ条件の取得

• research.md がある場合: その「受け入れ条件」セクションから AC を読み込む
• research.md が無い場合: gh issue view で issue を取得し、AC を抽出する。issue に AC が無い・曖昧な場合は AskUserQuestion でユーザーに確認する(本来 /research で行う作業の fallback。auto では確認せず、抽出した AC と置いた仮定を plan.md に明記する)

4. 実装方法の選択

• research.md の「実装方法の候補」セクションから候補を読み込む
• 各候補の概要・Pros / Cons・推奨度を整理して AskUserQuestion で ユーザーに選択してもらう(自由入力でのフィードバックも受け付ける)。auto の場合は質問せず推奨度最上位の案を採用し、選択理由を plan.md に記録する
• research.md が無い場合は本スキル内でコードベース調査 + 候補列挙を行ってから選択する
• 再計画モード(既存 plan.md がある)の場合: 既存計画で選択された方式を尊重し、変更が必要な場合のみ再選択する(auto 以外はユーザーに確認)

5. 副作用 identifier の抽出

選択された実装方法から、変更が引き起こす 副作用 identifier(コードに直接現れない間接依存の起点)を洗い出す。例:

• データ書き込み: コレクション名 / テーブル名 / ドキュメントパスのパターン(orders/{orderId} など)
• イベント発火: イベント名 / トピック名 / channel 名
• キュー投入: キュー名 / job 名
• ファイル出力: バケット名 / パスプレフィックス
• HTTP 発火: URL パス / endpoint 名
• 設定書き込み: 設定キー / feature flag 名

抽出方法:

• 変更対象コードに含まれる書き込み系 API 呼び出し(.set() .update() publish() emit() enqueue() 等)から identifier を列挙
• step 1 で読み込んだ config.json の attentions のうち、該当する identifier に関する注意点を波及範囲に組み込む

6. 受け入れ条件カバレッジ・タスク策定

選択された方法・AC・副作用 identifier をもとに、TDD(Red → Green → Refactor)の流れで実装計画を立てる。

• 各タスクは「テストを書く(Red)→ 実装する(Green)→ /simplify でリファクタリングする(Refactor)」の順で構成する
• 各タスクの影響範囲(対象ファイル・関数)、具体的な変更内容、完了条件を特定する
• step 5 で抽出した副作用 identifier の波及先(trigger / subscriber / consumer 等)も影響範囲に含める
• AC ごとに対応タスクをマッピングする(AC1 → タスク 1, 2 のように、全 AC が 1 つ以上のタスクで満たされる状態にする)。マッピングできない AC があればタスク追加を検討する

7. 完了の定義(Definition of Done)の策定

タスクが全て完了した上で 「この issue 全体として何を満たせば完了とみなすか」 を明文化する。各タスク単位の完了条件(step 6)とは別に、issue 全体の合格基準として /dev の DoD ゲート(plan / implement / test / review のループ脱出条件) になる。

以下のカテゴリで漏れなく定義する:

• AC 充足: research で確定した全 AC が満たされていること(チェック方法も明記)
• テスト: 既存テストが全て通る / 新規テストの最低カバレッジ / checklist.html の全項目が pass(チェックリスト本体は step 8 で作成し、DoD からは参照する)
• 副作用検証: step 5 で抽出した副作用 identifier の波及先が想定どおり動作する(trigger 起動、subscriber 受信、設定反映など)
• コード品質: lint / type check / /simplify 通過、デバッグログ・コメント残骸の除去
• ドキュメント: 必要に応じて README / 設定ファイル / コメントの更新
• 後方互換性 / マイグレーション: 既存データやクライアントへの影響対応(必要な場合のみ)

各項目は 検証可能な粒度 で書く(「動作確認した」ではなく「checklist.html の項目が全 pass」のように、何をもって満たしたとみなすかが明確であること)。issue 固有の合格基準(性能目標、UI 仕様、外部連携の挙動など)も加える。

再計画モードでは既存の DoD を尊重し、追加要件があれば追記する。

8. 動作確認チェックリスト(checklist.html)の作成

AC・タスク・副作用 identifier を起点に、tmp/issues/<issue番号>/checklist.html を plan.html とは別ファイルとして 作成する(/test がチェック結果を書き込むため、計画書とは分離する)。

• 各 AC を満たすことを確認するための具体的なブラウザ操作・期待結果を記述する
• AC ごとに 正常系・異常系・エッジケース を網羅する(AC が「不正入力でエラー」なら、各種不正パターンを列挙)
• チェックリスト項目には対応する AC 番号を併記する(例: [AC1] 不正なメールでエラーが表示される)
• 副作用 identifier の波及先確認(trigger 起動・通知送信など)も項目に含める
• AC で明示されていないが確認が必要な観点(パフォーマンス・他機能への影響・UI 崩れなど)は 補助項目 として明示的に分けて追加する
• 各チェック項目は <input type="checkbox"> でブラウザ上で進捗を追えるようにする

必須セクション(見出しとして含める): 前提条件(環境・テストデータ等)/ 正常系 / 異常系 / エッジケース / 補助項目。

再計画モードでは既存 checklist.html を更新する。内容が変わらない項目の checked 状態(前回のテスト結果)は保持する。

9. plan.md / plan.html への書き出し(2 種生成)

計画を tmp/issues/<issue番号>/plan.md に書き出す(md が正。後続スキル /review-plan / /implement / /dev 等はこちらを読む)。続けて同じ内容を人間のレビュー用に plan.html としてレンダリングする(TDD フェーズの色分け・<details> 折りたたみ・Mermaid 図などのリッチ表現はこちらに)。

• 再計画モードでは md を更新してから html を再生成する(html だけを編集しない)
• checklist.html は例外として html 単一のまま(/test がチェック結果を書き込む状態ファイルのため。step 8 参照)

出力構造(必須セクション)

レイアウトやスタイル、図表の有無・種類は計画内容に応じて自由に設計してよい(テンプレートは置かない)。ただし他スキルが情報を抽出できるよう、以下のセクションは md の見出し(##)として含めること(html も同構成にする)。

• 概要: issue の目的と背景
• 選択された実装方法: 採用した方法と選択理由(auto の場合は自動決定の根拠と置いた仮定も)
• 受け入れ条件カバレッジ: AC ↔ タスクの対応表(テーブル推奨)
• 副作用 identifier: 書き込み先・発火イベント・設定キー等の列挙と、想定される波及先
• タスク一覧: 各タスクのタイトル(依存関係も)
• タスク詳細: 各タスクの影響範囲・Red / Green / Refactor の各フェーズ・完了条件
• 完了の定義(Definition of Done): カテゴリごとの合格基準を検証可能な粒度で列挙(チェックボックスで表現するのが望ましい)

処理フロー・データフロー・コンポーネント関係・状態遷移などが計画の理解を助ける場合は、Mermaid や SVG で図を積極的に追加してよい。

注意事項

• 実装方法の 選択は本スキルが行う(/research は候補列挙までで選択しない)
• 受け入れ条件は本スキルでは原則新規作成しない(/research で確定済みのものを使う)。research が無い場合のみ fallback として本スキルで AC を確定する
• チェックリストの項目は AC を起点に作る(AC こそが「動作する」の定義)。AC をカバーしない項目は補助項目として明示する
• issue の内容が曖昧で計画に落とし込めない部分がある場合は、ユーザーに確認を取る(auto では保守的な解釈を採用し、仮定として plan.md に明記する)
• config.json の attentions は LLM が解釈する自然言語のメモ。形式を厳密に判定せず、関連しそうな注意点は積極的に計画に反映する