Imported from takashabe/dotfiles (.claude/skills/plan-refine/SKILL.md). Install upstream with npx skills add takashabe/dotfiles --skill plan-refine. Copyright stays with the author.

Plan Refine

実装プラン/設計ドキュメントを別系統 LLM の Codex でクロスチェックし、指摘の取捨選択 → 検証 → プラン修正まで回して磨き込むサイクル。実装着手前に使う。

設計思想（このスキルが encode していること）

通常のレビュースキルと違い、ここは「Codex を回す」こと自体ではなく 回し方の規律 を encode する。過去の反省から得た4原則:

1. discovery は基本1パス。「指摘がなくなるまでループ」はしない。単一レビュアーが黙ることは正しさの証明ではなく、言うことを言い尽くしただけ。停止条件にすると偽の安心を encode する。
2. 反復は discovery のやり直しではなく fix-verification。追加ラウンドの価値は「もっと粗探しする」ことではなく「自分が入れた修正が嘘をついていない・新たな矛盾を生んでいないことを確かめる」ことにある。条件付き・上限あり。
3. Codex は peer であって権威ではない。採用する指摘、特に Codex の 修正案 はコード/実機に当ててから反映する。Codex はその環境で動かない案を自信を持って出すことがある（知識カットオフ・エミュレータ差異など）。鵜呑みは品質を下げる。
4. 停止は "clean" ではなく residual-risk の明示。未検証事項（行番号ドリフト、実装でしか出ないバグ、単一レビュアーの盲点）を出力して締める。

関連スキル

• plan-codex-review（名前が逆順・別物）: 3ロール（設計/運用セキュ/品質テスト）並列の discovery 専用。独立した観点を並列でぶつけて広く拾いたいときはそちら。
• 本スキルは discovery + トリアージ + 検証 + 修正 + 条件付き反復 の磨き込みサイクルに重心がある。広い discovery が欲しければ Step 2 を plan-codex-review の並列 discovery に差し替えてもよい。

Step 0: モデルと effort の確認

AskUserQuestion で model と reasoning effort を1プロンプト2問で聞く。

• model: 現行の codex 系最新モデルを推奨（プランレビューは技術精度が要るため）。ユーザーが使えるモデルを提示する。
• effort: high または xhigh を推奨。xhigh は最精度だが遅い。
• sandbox は read-only 固定。レビューで Codex にファイルを書かせない。プラン修正は Claude が Edit で行う。

Step 1: プランファイルの解決

$ARGUMENTS のパスを優先。未指定なら以下の順で探索:

1. 作業ディレクトリ直下の PLAN.md / plan.md
2. .plans/ 配下の最も直近更新された .md
3. プロジェクトルート（git rev-parse --show-toplevel）配下の PLAN.md

一意に決まらなければユーザーに確認する。勝手に新規ファイルを作らない。確定後 Read で全文読み（トリアージに必要）、絶対パスを $PLAN_PATH に記録。要求仕様/元ネタの doc がプラン内で参照されていれば、そのパスも控える（discovery プロンプトに渡す）。

Step 2: discovery（多レンズ1パス）

高利得レンズを埋め込んだ単一 Codex パスを実行する。レンズはプラン固有の弱点を当てにいくのではなく、「プランレビューをすり抜けるエラークラス」を固定で当てる（だから再利用が効く）。

レンズ（discovery プロンプトに必ず含める）

1. False-green 検証 — プラン内の検証/テスト戦略が、それが守ると主張する失敗を実際に検知できる粒度になっているか。例: 集計の検証が「総数の一致」だけを見ていて、内訳（粒度・属性別）の崩れを見逃す。プランは「厳密そうに見えて間違った粒度を見ている検証」を平気で含む。最高利得。
2. 初回本番限定の失敗 — テスト・CI・エミュレータを全部通っても、初回の実環境実行で初めて出る前提。IAM/権限、パーティションフィルタ、タイムアウト、quota、env 固有値（設定の silent fallback）、cold-start。構造的にテストで捕まえられない。
3. 過大主張 — 「fail-fast」「挙動不変」「等価」「冪等」をメカニズムが支える以上に強く言っている箇所。プランは楽観で嘘をつく。主張と機構のギャップを突く。
4. コード境界の罠 — bind/シグネチャ/API/型の食い違いなど、散文がごまかしている具体。stakes は低い（実装時のテストで自己修正されやすい）が指摘は安い。
5. 内部整合性 — PR/ステップ分割の依存関係、セクション間の相互参照、行番号や定数の整合。

discovery 実行

CWD="$(pwd)"
PLAN_DIR="$(dirname "$PLAN_PATH")"
ADD_DIR_ARGS=""
case "$PLAN_DIR" in
  "$CWD"*) ;;
  *) ADD_DIR_ARGS="--add-dir $PLAN_DIR" ;;
esac

codex exec --skip-git-repo-check -m "<model>" \
  --config model_reasoning_effort="<effort>" \
  --sandbox read-only -C "$CWD" $ADD_DIR_ARGS \
  "<discovery プロンプト>" 2>/dev/null

discovery プロンプトの骨子:

• 役割: 当該ドメインの Principal Software Engineer としてプランをレビュー。
• 前提の明示: 要求仕様 doc / プランが参照する既存コードのパス。プラン内の行番号がどのリビジョン基準か（例: origin/dev）。Codex に「git show <ref>:<path> で実コードに当てて検証してよい」と促す。
• 上記5レンズを観点として列挙。
• 出力形式: 各指摘を severity(critical/major/minor) / 該当セクション / 問題点 / 影響 / 修正案 で列挙。
• 抑制指示: 重箱の隅・好みの問題は出さない。実装・運用に実害がある指摘のみ。指摘ゼロなら「指摘なし」のみ。

2>/dev/null で thinking tokens を抑制（デバッグ時のみ stderr を見る）。Bash の timeout は 600000 (10分)。

Step 3: トリアージ（severity × catch-stage）

discovery の各指摘を2軸で分類する。severity だけで見ない — 全指摘が等価に見えると本当に効く指摘が埋もれる。

• severity: critical / major / minor（実害の大きさ）
• catch-stage: その指摘は後工程で確実に捕まるか。「実装時のユニット/ハンドラテスト・CI・通常のコードレビューで自己修正される」ものは降格。

採用候補 = high-stakes かつ後工程で捕まらない（または捕まっても手戻りが大きい） もの。レンズ1・2 由来の指摘がここに来やすい。自己修正される minor（レンズ4 由来が多い）は記録だけして降格し、プランには「実装時に注意」程度で残す。

Step 4: verify-before-apply

採用候補、特に Codex の修正案を、反映前に検証する。

• 実コードに当てる: git show <ref>:<path> / Grep / Read でパス・シグネチャ・既存パターンを確認。
• 必要なら実機検証: ツールの実挙動が論点なら実際に動かす（例: エミュレータが特定機能をサポートするか）。
• Codex の案がその環境で成立しないことが分かったら、案を捨て、自前の代替を採る。その「Codex 案を退けた事実と代替判断の根拠」をプランに記録する（後から第三者が追える形で）。
• 検証で指摘自体が誤りと分かったら却下。却下理由を Step 7 に残す。

この Step を省くと、レビューがプランを悪化させるリスクがある。必ず通す。

Step 5: プラン修正

検証を通った指摘を Edit でプランに反映する。

• 反映前に差分の要点をユーザーに提示し、承認を得てから書き込む。ユーザーの明示指示なしにプランを書き換えない。
• 反映は最小差分で。プランの既存の語彙・構成に合わせる。
• 指摘が複数セクションに波及する場合、相互参照（PR番号、Verification、リスク欄など）も同時に整合させる。

Step 6: 反復判断（条件付き fix-verification）

Step 5 の修正後、以下のトリガーを評価し、発火したものを必ず書き出す（判断を vibes でなく監査可能にする）:

• 修正が load-bearing な主張 を書き換えた（fail-fast の範囲、等価性の根拠、挙動不変の宣言、スコープ境界など）。詳細・例の追記は該当しない。
• 修正が 複数セクションの整合に依存する箇所 を変えた（PR境界、依存関係、検証手順の構造）。
• Codex の提案を採れず、自前の代替に差し替えた（その代替は誰もレビューしていない）。
• high severity の指摘が、追記でなく構造変更を要求した。

1つでも該当 → fix-verification を1回回す。対象は「自分が触った差分 + その整合」だけ。discovery はやり直さない。 1つも該当 → 反復せず Step 7へ。

echo "<入れた修正の要点。特に load-bearing な書き換えと、Codex 案を退けて差し替えた箇所。
これらが過大主張・新たな矛盾・整合崩れを生んでいないかだけ再確認してほしい。
新規の粗探しは不要。問題なければ「指摘なし」のみ。>" \
  | codex exec --skip-git-repo-check resume --last 2>/dev/null

resume では flag を付けない（model/effort/sandbox は元セッションを継承）。fix-verification で新たな指摘が出たら Step 3〜5 をその差分についてのみ回す。

ハードキャップ: 追加ラウンドは最大2回。それを超えても収束しないなら、残課題を residual-risk として Step 7 に明記して止める。「指摘がなくなるまで」は禁止。

Step 7: 締め（residual-risk 出力）

"clean" とは言わない。 以下を提示してサイクルを閉じる:

## Plan Refine 結果

**対象**: <$PLAN_PATH>
**model / effort**: <...> / <...>
**ラウンド数**: discovery 1 + fix-verification <n>（トリガー: <発火したトリガー、なければ「なし」>）

### 反映した指摘
- <severity> <要点> — <どう直したか>

### 却下した指摘（根拠）
- <要点> — <検証で覆った/後工程で自己修正されるため降格 等>

### Codex 案を退けた箇所（あれば）
- <Codex の案> → <自前の代替と根拠（検証結果）>

### Residual Risk（未検証事項・このレビューでは担保されないもの）
- 行番号/シグネチャのドリフト（プランは <ref> 時点。実装着手時に再確認）
- 実装でしか出ないバグ（Codex は文書をレビューしただけ）
- 単一レビュアーの盲点 / Codex の知識カットオフ
- <このプラン固有に残る確認事項>

### 推奨次アクション
- <実装着手 / 追加の人手レビュー / 特定箇所の dev 実機検証 など>

注意事項

• ユーザーの明示指示なしにプランファイルを書き換えない。差分提示 → 承認 → Edit。
• このスキルはレビューとプラン修正のみ。実装・git 操作はしない。
• Codex が認証切れ等で失敗したら codex login を促し、勝手にリトライしない。
• Codex の指摘・修正案は常に Claude 側の視点で妥当性を検討する（Step 4）。矛盾があれば両論併記でユーザーに委ねる。