review-plan

/plan が作成した tmp/issues/<issue番号>/plan.md と checklist.html を独立視点でレビューし、影響範囲の見積もり漏れを検出する。$ARGUMENTS は issue 番号(123、#123)または URL。

目的

/plan の手戻り原因として最大なのは「影響範囲の見落とし」。特にコードに直接現れない間接依存(DB trigger / イベント subscriber / scheduled job / 暗黙の必須セット等)を見落とすと、/test や /review で発覚して再計画ループになる。本スキルは plan を読むだけでなく 独立にコードベースを grep して検証 し、見落としがあれば差し戻す。

独立性について: 本スキルは /dev からはサブエージェント(plan 作成の文脈を持たない別コンテキスト)として実行される。それ自体が独立性の担保になっている。単独で(同一会話内で)実行される場合も、plan の主張を鵜呑みにせず必ず一次情報(コード)で検証すること。ユーザーへの質問はできない前提で動作し、判断に迷う場合は保守的(修正必須)に倒してその根拠を成果物に明記する。

手順

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

プロジェクト(git root)の .agents/skills-config/review-plan/config.json を読み込み、attentions 配列に記載されたプロジェクト固有の注意点を把握する。ファイルが無ければ注意点なしとして続行する。レビュー時にこれらの注意点が plan に反映されているか照合する。

2. plan / checklist / research の読み込み

tmp/issues/<issue番号>/plan.md と checklist.html を読み込む(md が無ければ plan.html。以降も同様)。plan が存在しない場合は呼び出し元にエラーを報告して終了。 tmp/issues/<issue番号>/research.md も読み込む(受け入れ条件・未確認の仮定・盲点候補の照合に使う。無ければ plan の「受け入れ条件カバレッジ」セクションから AC を取得)。

plan から以下を抽出する:

• 副作用 identifier セクション に列挙された identifier
• 受け入れ条件カバレッジ の AC → タスクマッピング
• タスク詳細 の「対象ファイル」「変更内容」に挙げられたシンボル・ファイル

3. 受け入れ条件カバレッジの検証

research.md の AC(または plan のカバレッジ表)に対して、以下を確認:

• 全 AC が plan のタスクでカバーされているか
• 「対応タスク」欄が空の AC が無いか
• マッピングされているタスクの完了条件が、その AC を実際に検証する形になっているか
• AC とタスクの粒度齟齬(1 タスクに過剰な AC が紐付いていないか、逆も)

さらに checklist.html のカバレッジ も検証する:

• 全 AC に対応するチェック項目が 1 つ以上あるか(AC 番号の併記で照合)
• AC に紐づかない項目が「補助項目」として明示されているか
• 各項目の操作手順・期待結果が検証可能な粒度か(「正しく動く」のような曖昧な期待になっていないか)
• 副作用 identifier の波及先確認(trigger 起動・通知送信など)が項目に含まれているか

カバーされていない AC や、明らかに検証不能なマッピング・項目は 修正必須 として扱う。

4. 影響範囲の独立検証

4-1. 副作用 identifier の逆引き grep

step 2 で抽出した各 identifier について、コードベース全体に対して文字列 grep を実行する。

• 書き込み API 呼び出し以外で identifier を参照している箇所を抽出
• → trigger / subscriber / consumer / 設定参照の候補

検出した参照箇所が plan の影響範囲に含まれているか照合。

4-2. config.json attentions との照合

step 1 で読み込んだ各 attention について、plan の変更対象が該当するか判定する。

• 該当する場合、attention に記載された波及先・必須セット・確認項目が plan に反映されているか確認
• 反映されていない項目を抽出

4-3. 直接参照の補助確認

plan が変更対象として挙げた関数・型・コンポーネントについて、grep で参照元を確認し、plan が参照元の修正を漏らしていないか確認(既存の plan で大半はカバーされる想定)。

4-4. ヒューリスティック盲点パス(blind spot pass)

4-1〜4-3 の機械的検証は 既知の identifier・シンボルしか辿れない。それでは拾えない unknown unknowns を、観点チェックリストで plan を走査して探す:

• 権限・認可(新しい操作に対する権限チェックは計画されているか)
• 並行性・競合(同時実行・二重送信・トランザクション境界)
• エラーパス・リトライ(失敗時の状態・部分的成功の扱い)
• データ移行・後方互換(既存データ・既存クライアントへの影響)
• ロールバック・切り戻し(リリース後に戻せる設計か)
• 監視・ログ(障害時に気づける・追える状態か)
• 性能(データ量が増えたときに破綻しないか)

research.md の「盲点候補」「未確認の仮定」が plan で対処・言及されているかも照合する。該当する懸念が実際にコード上の根拠を持つ場合のみ指摘する(観点を機械的に全部挙げない)。

5. 検証結果の出力(2 種生成)

検証結果を tmp/issues/<issue番号>/review-plan.md に書き出す(md が正。/dev と /plan はこちらを読む)。続けて同じ内容を人間用に review-plan.html としてレンダリングする(must / should / OK の色分け・<details> での検証根拠の折りたたみなどはこちらに)。

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

レイアウトや図表は内容に応じて自由に設計してよい(テンプレートは置かない)。ただし /dev や /plan がレビュー結果を判定できるよう、以下のセクションは md の見出し(##)として含めること(html も同構成にする)。

• サマリ: 修正必須 / 任意改善 / OK の件数、判定(差し戻し必要 / OK)
• 受け入れ条件カバレッジ: AC ごとのカバー状況 — plan タスクと checklist 項目の両方(テーブル推奨)
• 修正必須 (must): 各指摘について該当箇所・検証根拠・提案
• 任意改善 (should): 各改善案について該当箇所・提案
• 盲点パス所見: 4-4 で確認した観点と結果(問題なしの観点は簡潔に)
• OK: 検証して問題なかった項目

波及関係や影響範囲を図で示すと理解が早い場合は、Mermaid で依存グラフを追加してよい。

各指摘は以下のいずれかに分類:

• 修正必須 (must): 影響範囲が欠落している、間接依存が見落とされている、AC がカバーされていない → /plan への差し戻し対象
• 任意改善 (should): 改善余地はあるが必須ではない
• OK: 問題なし

6. 判定と呼び出し元への報告

• 修正必須が 1 件以上: 「/plan への差し戻しが必要」と判定
• 修正必須 0 件: レビュー OK として完了

サブエージェントとして実行されている場合は、最終メッセージとして次を返す: 判定(OK / 差し戻し)、must / should / OK の件数、must の要旨(1 行ずつ)。詳細は review-plan.md / review-plan.html を参照するよう添える。

注意事項

• plan を再読するだけでなく、必ず独立にコードベースを grep して検証する(セルフレビュー化を防ぐ)
• 検索は Grep ツールまたは git grep / rg を使う。Bash の grep -r / find <dir> は gitignore された .secret.local 等の deny ルール対象ファイルを走査して承認待ちになるため使わない(やむを得ず使う場合は --exclude='.secret*' --exclude-dir=node_modules を付ける)
• config.json の attentions は LLM が解釈する自然言語のメモ。形式判定せず、関連しそうなら積極的に照合する
• 修正必須・任意改善の境界判断に迷う場合は、影響の波及範囲・データ整合性への影響を優先して 修正必須に倒す
• 軽微な表現や好みの問題は指摘しない(plan の構成や文章スタイルなど)