| name | validating-iteration-plan |
| description | イテレーション計画と上流設計ドキュメント群（ユーザーストーリー、ドメインモデル、データモデル、UI 設計）との整合性を検証する。「イテレーション計画を検証したい」「計画の整合性をチェックして」「イテレーション計画を作成した」「計画と設計ドキュメントの不整合を確認したい」といった場面で発動する。planning-releases でイテレーション計画を作成した直後にも積極的に使用すること。計画作成後に必ず本検証を実施することで、開発着手前にドキュメント間の不整合を検知・修正できる。 |
イテレーション計画の整合性検証
イテレーション計画は複数の設計ドキュメントから情報を引用・参照するため、ドキュメント間の不整合がそのまま実装の不整合に直結する。計画作成後に本検証を実施し、開発着手前に不整合を検知・修正する。
検証対象ドキュメント
| # | 検証対象 | パス | 検証内容 |
|---|
| 1 | ユーザーストーリー | docs/requirements/user_story.md | ストーリー ID・タイトル・アクター・受入基準の一致 |
| 2 | ドメインモデル | docs/design/domain-model.md | 集約・エンティティ・値オブジェクトの名称・構造・関連の一致 |
| 3 | データモデル | docs/design/data-model.md | テーブル名・カラム名・型・制約・命名規約の一致 |
| 4 | UI 設計（ビュー） | docs/design/ui_design.md | ワイヤーフレーム構造・ナビバー形式・テーブル表記・URL パスの一致 |
| 5 | UI 設計（インタラクション） | docs/design/ui_design.md | 画面遷移・htmx パターン・PRG パターン・エラー処理・フィードバックメッセージの一致 |
| 6 | ゴールの整合性 | イテレーション計画全体 | ゴール・ストーリー・設計・タスク・見積もりの内部整合性 |
| 7 | 過去レビュー指摘事項 | docs/review/ 内の最新レビューファイル | 高・中優先度の指摘がストーリーまたはタスクとして計画に反映されているか |
検証手順
7 ステップを順に実行する。各ステップは並列実行も可能。不整合を発見した場合はイテレーション計画を修正し、変更点を注記する。
ステップ 1: ユーザーストーリーとの整合性
イテレーション計画の「ストーリー詳細」セクションと user_story.md を比較する。
チェック項目:
よくある不整合:
- ストーリー文の一部省略（例: 「予約情報」-> 元は「予約情報（出発地・目的地・期限・貨物仕様）」）
- 受入基準の列挙が省略されている（例: 制約条件の具体名が省略）
ステップ 2: ドメインモデルとの整合性
イテレーション計画の「設計 > ドメインモデル」セクションと domain-model.md を比較する。
チェック項目:
よくある不整合:
- 既存の値オブジェクト名と異なる名称を使用（例:
Schedule -> VoyageSchedule）
- 既存の集約構造（親子関係）を無視した新規モデル設計
- 共有カーネル（
Location）を参照せず、直接 String で locode を保持
ステップ 3: データモデルとの整合性
イテレーション計画の「設計 > データモデル」セクションと data-model.md を比較する。
チェック項目:
よくある不整合:
- テーブル名が複数形（
voyages）-> data-model.md は単数形（voyage）
- PK が業務キー直接（
voyage_number PRIMARY KEY）-> 規約はサロゲートキー + UK
- FK が業務キー参照（
REFERENCES voyages(voyage_number)）-> 規約は voyage.id 参照
- PostgreSQL 構文（
BIGSERIAL）と MySQL 構文（AUTO_INCREMENT）の混在
ステップ 4: UI 設計（ビュー）との整合性
イテレーション計画の「設計 > ユーザーインターフェース > ビュー」セクションと ui_design.md を比較する。
チェック項目:
よくある不整合:
- 独自のナビバー構造を使用
- テーブルヘッダーの表記形式が異なる
- URL パスが未定義
- 既存画面との関係（拡張 vs 新規）が不明確
ステップ 5: UI 設計（インタラクション）との整合性
イテレーション計画の「設計 > ユーザーインターフェース > インタラクション」セクションと ui_design.md の画面遷移図・htmx パターン・フィードバック規約を比較する。
チェック項目:
よくある不整合:
- バリデーションエラー自己ループ遷移の欠落
- htmx パターンの記述がない（画面遷移図のみで動的更新方式が不明）
- フィードバックメッセージの定義がない
- 既存画面 state との遷移関係が切断されている
ステップ 6: ゴールの整合性（最終確認）
イテレーション計画全体を俯瞰し、イテレーションのゴールと各ストーリー・設計・タスクが一貫しているかを確認する。ステップ 1-5 が個別ドキュメントとの突合であるのに対し、本ステップは計画内部の論理的整合性を検証する最終関門である。
チェック項目:
よくある不整合:
- ゴールが抽象的すぎて達成条件が判断できない（例: 「航路管理機能を改善する」→ 具体的な完了基準がない）
- ゴールに対して過剰なストーリーが含まれている（スコープクリープ）
- 設計セクションの内容がストーリーの一部しかカバーしていない
- タスク分割が設計セクションと対応していない（設計にあるがタスクにない、またはその逆）
- ベロシティを超えるポイントが計画されている
ステップ 7: 過去レビュー指摘事項との整合性
docs/review/ 内の最新レビューファイルを確認し、前イテレーションで発見された指摘事項が今回の計画に適切に反映されているかを検証する。コードレビュー（*_review_*.md）・UI/UX レビュー（*_uiux_review_*.md）・分析レビュー（*_review_*.md）のいずれも対象とする。
チェック項目:
確認対象レビューファイルの特定方法:
docs/review/index.md のレビュー一覧テーブルを確認する- 今回計画するイテレーション番号の直前イテレーションに対応するレビューファイルを抽出する
- 複数のレビュー種別（コードレビュー + UI/UX レビュー）がある場合はすべて確認する
よくある不整合:
- 高優先度の指摘が計画に含まれておらず、対応方針の記載もない（暗黙の未対応）
- 前イテレーションで「IT(N+1) 対応」と明記された指摘が、IT(N+1) の計画に含まれていない
- 受入基準の修正が必要な指摘（例: 未実装フィールド、仕様乖離）が設計セクションに反映されていない
- レビューで指摘された UI の日本語化・バリデーション修正がタスクとして計画されていない
検証結果の報告
検証完了後、以下の形式で報告する。
## 整合性検証結果
### 検証対象
- イテレーション計画: `docs/development/iteration_plan-N.md`
### 検証結果サマリー
| ステップ | 検証対象 | 結果 | 不整合件数 |
|---------|---------|------|-----------|
| 1 | ユーザーストーリー | OK / NG | N 件 |
| 2 | ドメインモデル | OK / NG | N 件 |
| 3 | データモデル | OK / NG | N 件 |
| 4 | UI 設計（ビュー） | OK / NG | N 件 |
| 5 | UI 設計（インタラクション） | OK / NG | N 件 |
| 6 | ゴールの整合性 | OK / NG | N 件 |
| 7 | 過去レビュー指摘事項 | OK / NG | N 件 |
### 不整合一覧（NG の場合のみ）
#### ステップ N: 〇〇との不整合
| # | 不整合内容 | 計画の記述 | 正しい記述（ドキュメント準拠） | 修正要否 |
|---|----------|-----------|---------------------------|---------|
| 1 | ... | ... | ... | 要修正 |
注意事項
- 検証は計画作成直後に実施する（開発着手前に不整合を解消する）
- 既存ドキュメントへの反映が必要な変更点は、イテレーション計画内に「注」として明記する
- イテレーション完了時に、注記された変更点を各設計ドキュメントに反映する
- 不整合を発見した場合、イテレーション計画側を設計ドキュメントに合わせて修正する（設計ドキュメントが正）
