---
description: Validate and improve an implementation plan in plan mode by cross-checking with docs/design/*.md, docs/ROADMAP.md, docs/requirements.md, and src/. Superset of update-design. Use in plan mode whenever the user requests an implementation plan for zghalint - invoke at the start of plan mode so the verification runs before finalizing the plan file, and re-invoke just before ExitPlanMode if the plan has materially changed. Trigger examples - entering plan mode for any zghalint feature work, "プランを作成", "実装計画", "plan this feature", "validate the plan", "整合性チェック".
---

# update-plan

プランモードで実装計画を完成させた直後、ユーザーに提示する直前に発動する統合検証・改善スキル。
update-design の全機能（設計書品質評価）を内包しつつ、ロードマップ・要件定義との横断的整合性チェックと、プラン自体の改善を行う。

## 発動タイミング

**プランモードでプラン完了と判断した直後、`ExitPlanMode` を呼ぶ直前**に本スキルを実行する。

フロー:
1. ユーザーが実装タスクを依頼する
2. Claude がプランモードで調査・計画を作成する
3. プランが完成した時点で **本スキルを発動**
4. 本スキルの検証結果に基づきプランを改善する
5. 改善済みプランで `ExitPlanMode` を呼ぶ

## Phase 1: コンテキスト収集

1. 作成中のプランファイルの内容を把握し、対象の機能・Phase・モジュールを特定する
2. プランに関連する `docs/design/*.md`、`docs/ROADMAP.md`、`docs/requirements.md` を読み込む
3. プランが対象とするモジュールの `src/` 配下のソースコードを読み込む

## Phase 2: 設計書品質評価（update-design 完全互換）

プランが関連する設計書を以下のカテゴリで評価する。

### 評価カテゴリ

1. **モジュール・構造体設計**
   - Zigモジュールの責務分離が適切か
   - 構造体（struct）のフィールド定義が明確か
   - インターフェース（関数ポインタ・comptime）の設計が適切か

2. **YAMLパーサ・ワークフロー解析設計**
   - 自前YAMLパーサ（tokenizer/parser/types）の設計が適切か
   - ワークフローパーサとバリデータの責務分離が明確か
   - GitHub Actionsワークフローの構造（jobs/steps/triggers）のモデリングが適切か

3. **エラーハンドリング設計**
   - Zigのerror union型の使い方が適切か
   - Diagnostics（診断メッセージ）の型階層・重要度設計が明確か
   - エラー位置情報（Span）の伝播が適切か

4. **技術選定の根拠**
   - ゼロ依存方針の理由が明記されているか
   - YAML自前実装の設計判断が記載されているか
   - 出力形式（terminal/JSON/SARIF）の選定理由が明記されているか

5. **データフロー**
   - 入力（YAMLファイル）からトークン化→AST→ワークフロー型→ルール適用→診断出力までのフローが明確か
   - ルールエンジンの実行フローが記載されているか

### 評価基準

各カテゴリを100点満点で評価する。**合格ライン: 90点以上**

| スコア | レベル | 意味 |
|--------|--------|------|
| 90-100 | 優秀 | 設計が明確で実装に即座に移れる。補足不要 |
| 70-89 | 良好 | 実装に移れるが、軽微な補足があるとなお良い |
| 50-69 | 改善推奨 | 理解可能だが、補足・明確化が望ましい |
| 30-49 | 要改善 | 設計が不明確で、実装前に修正が必要 |
| 1-29 | 重大不備 | 該当セクションが欠落、または根本的な設計ミス |

スコアリングの目安:
- **100**: 全サブ項目が完全に記載され、実装者が迷う余地がない
- **90**: 主要な設計判断が全て記載され、実装に十分な詳細がある
- **70-80**: 主要な設計判断が記載されているが、一部補足が望ましい
- **50-60**: 基本方針は理解できるが、具体的な型定義やAPIの詳細が不足
- **30-40**: 概要レベルの記述のみで、実装に必要な詳細が大幅に不足
- **10-20**: セクションは存在するが内容が断片的
- **1-9**: セクションが実質的に欠落

## Phase 3: 整合性チェック

設計書・ロードマップ・要件定義・ソースコード間の不整合を検出する。

### 3-1. 設計書 ↔ ソースコード

1. 設計書に記載されたモジュール・構造体・関数シグネチャが実装と一致しているか確認する
2. 設計書に記載されているが未実装の機能を特定する
3. 実装されているが設計書に記載されていない機能を特定する

### 3-2. ロードマップ ↔ 設計書 ↔ 要件定義

1. プランが対象とする Phase に対応する設計書が存在するか確認する
2. プランが対象とする Phase が要件定義の FR/NFR のどれに対応するか確認する
3. 要件定義の状態（✅ / 🔲）がロードマップのステータスと一致しているか確認する
4. ドキュメント間で言及されているがカバーされていない機能・要件を特定する

## Phase 4: プラン改善と出力

Phase 2〜3 の結果に基づき、プランを改善する。

### 4-1. プランの検証

1. **Tidy First?**: 構造的変更と機能的変更が分離されているか
2. **イテレーション単位**: 各ステップが最小単位で分割されているか
3. **影響範囲**: プランが変更するモジュールに依存する他のモジュールへの影響が考慮されているか
4. **設計書提案**: プランが対象とする Phase に設計書が存在しない場合、既存設計書の標準セクション構成（概要→技術選定→型定義→エラー型→公開API→データフロー→テスト戦略→イテレーション）に従ったアウトラインをプランに追加する

### 4-2. フィードバック反映

発見した問題を優先度付きでプランに反映する:

- **P0（必須修正）**: スコア50未満のカテゴリが1つでもある場合、設計書との矛盾、要件定義に存在しない機能の追加
- **P1（推奨修正）**: スコア50-69のカテゴリがある場合、イテレーション分割の改善、影響範囲の追加記載
- **P2（情報提供）**: スコア70-89のカテゴリがある場合、既存設計書の改善余地、将来Phaseへの影響（90以上は指摘なし）

### 4-3. 検証サマリの出力

プランファイルの末尾に以下の検証サマリを追記する:

```markdown
## update-plan 検証結果

### 設計書品質評価
| 設計書 | モジュール設計 | YAML・WF解析 | エラー処理 | 技術選定 | データフロー | 平均 |
|--------|-------------|-------------|-----------|---------|------------|------|
| [名前] | XX/100 | XX/100 | XX/100 | XX/100 | XX/100 | XX.X |

**総合判定**: 🟢/🟡/🟠/🔴 [判定テキスト]

総合判定の基準:
- 🟢 実装着手可能: 平均 90 以上
- 🟡 軽微な改善後に着手可能: 平均 70-89
- 🟠 改善必要: 平均 50-69
- 🔴 大幅改善必要: 平均 50 未満

### 整合性チェック
| チェック項目 | スコア | 詳細 |
|-------------|--------|------|
| 設計書 ↔ ソースコード | XX/100 | [詳細] |
| ロードマップ ↔ 設計書 ↔ 要件定義 | XX/100 | [詳細] |

### 修正事項
- **P0**: [スコア50未満の必須修正の一覧]
- **P1**: [スコア50-69の推奨修正の一覧]
- **P2**: [スコア70-89の情報提供の一覧]
```

### 4-4. 完了アクション

1. P0・P1 の修正をプランに反映する
2. 検証サマリを付加した状態で `ExitPlanMode` を実行する

## 記述ルール

- コード例はZigで記述すること
- 設計書・レポートは日本語で記述すること
- 構造体名・関数名はZigの命名規則（camelCase / PascalCase）に従うこと
- 定数名はscreaming_snake_caseまたはZigの慣例に従うこと
- ロードマップ・要件定義のステータスは実装の実態に基づき、推測で変更しないこと
- プランの修正は根拠（設計書・要件定義・CLAUDE.md の該当箇所）を明示すること