validating-iteration-plan

name	validating-iteration-plan
description	イテレーション計画と上流設計ドキュメント群（ユーザーストーリー、ドメインモデル、データモデル、UI 設計）との整合性を検証する。「イテレーション計画を検証したい」「計画の整合性をチェックして」「イテレーション計画を作成した」「計画と設計ドキュメントの不整合を確認したい」といった場面で発動する。planning-releases でイテレーション計画を作成した直後にも積極的に使用すること。計画作成後に必ず本検証を実施することで、開発着手前にドキュメント間の不整合を検知・修正できる。

イテレーション計画の整合性検証

イテレーション計画は複数の設計ドキュメントから情報を引用・参照するため、ドキュメント間の不整合がそのまま実装の不整合に直結する。計画作成後に本検証を実施し、開発着手前に不整合を検知・修正する。

検証対象ドキュメント

#	検証対象	パス	検証内容
1	テンプレートフォーマット	docs/template/イテレーション計画.md	見出し構成・必須セクション・表形式・コードブロック形式の一致
2	ユーザーストーリー	docs/requirements/user_story.md	ストーリー ID・タイトル・アクター・受入基準の一致
3	ドメインモデル	docs/design/domain-model.md	集約・エンティティ・値オブジェクトの名称・構造・関連の一致
4	データモデル	docs/design/data-model.md	テーブル名・カラム名・型・制約・命名規約の一致
5	UI 設計（ビュー）	docs/design/ui_design.md	ワイヤーフレーム構造・ナビバー形式・テーブル表記・URL パスの一致
6	UI 設計（インタラクション）	docs/design/ui_design.md	画面遷移・htmx パターン・PRG パターン・エラー処理・フィードバックメッセージの一致
7	ゴールの整合性	イテレーション計画全体	ゴール・ストーリー・設計・タスク・見積もりの内部整合性
8	過去レビュー指摘事項	docs/review/ 内の最新レビューファイル	高・中優先度の指摘がストーリーまたはタスクとして計画に反映されているか

検証手順

8 ステップを順に実行する。各ステップは並列実行も可能。不整合を発見した場合はイテレーション計画を修正し、変更点を注記する。

ステップ 1: テンプレートフォーマットとの整合性

イテレーション計画全体が docs/template/イテレーション計画.md のフォーマットに従っているかを確認する。以降の内容整合性チェックに入る前に、見出し構成・必須セクション・表形式・コードブロック形式がテンプレートから逸脱していないことを検証する。

チェック項目:

• 文書タイトルが # イテレーション X 計画 形式になっている
• テンプレートの主要セクション（概要、ゴール、ユーザーストーリー、スケジュール、設計、リスクと対策、完了条件、更新履歴、関連ドキュメント）が揃っている
• 各セクションの見出しレベルがテンプレートと一致している
• 概要、対象ストーリー、タスク、リスク、更新履歴などの表形式がテンプレートの列構成に従っている
• mermaid、plantuml、prisma などのコードブロック種別がテンプレートと一致している
• 完了条件に Definition of Done と デモ項目 が含まれている
• 関連ドキュメント節に最低限の参照先が記載されている

よくある不整合:

• テンプレート必須セクションの欠落（例: 「更新履歴」がない）
• 見出し名や階層の変更（例: 「ユーザーストーリー」ではなく独自見出しを使用）
• 表の列不足や列名変更
• コードブロックの種別未指定、またはテンプレートと異なる記法

ステップ 2: ユーザーストーリーとの整合性

イテレーション計画の「ストーリー詳細」セクションと user_story.md を比較する。

チェック項目:

• ストーリー ID（US番号）が一致している
• ストーリータイトルが一致している
• アクター（「として」の部分）が一致している
• ストーリー文（「したい」「なぜなら」の部分）が一致している（省略なく全文一致）
• 受入基準の項目数と内容が一致している
• 対応 UC 番号が一致している

よくある不整合:

• ストーリー文の一部省略（例: 「予約情報」-> 元は「予約情報（出発地・目的地・期限・貨物仕様）」）
• 受入基準の列挙が省略されている（例: 制約条件の具体名が省略）

ステップ 3: ドメインモデルとの整合性

イテレーション計画の「設計 > ドメインモデル」セクションと domain-model.md を比較する。

チェック項目:

• 集約ルートの名称が一致している
• 値オブジェクトの名称・フィールドが一致している（例: Schedule vs VoyageSchedule）
• エンティティの名称・フィールドが一致している（例: CarrierMovement vs VoyageSchedule）
• 共有カーネル参照が正しい（例: Location を使うべき箇所で String になっていないか）
• 既存の集約構造を破壊する変更になっていないか
• 新規追加の場合、既存構造との関連が明記されているか
• domain-model.md への反映が必要な変更点が注記されているか

よくある不整合:

• 既存の値オブジェクト名と異なる名称を使用（例: Schedule -> VoyageSchedule）
• 既存の集約構造（親子関係）を無視した新規モデル設計
• 共有カーネル（Location）を参照せず、直接 String で locode を保持

ステップ 4: データモデルとの整合性

イテレーション計画の「設計 > データモデル」セクションと data-model.md を比較する。

チェック項目:

• テーブル名の単数形/複数形が data-model.md の規約と一致している
• PK 設計が一致している（サロゲートキー BIGSERIAL + 業務キー UK の規約）
• FK の参照先がサロゲートキー（id）を参照している（業務キー直接参照になっていないか）
• カラム名が一致している（例: departure_location_unlocode vs departure_location）
• データ型が一致している（例: TIMESTAMP vs DATE）
• 順序カラム名が一致している（例: seq_number vs sequence_order）
• 監査カラム（created_at・updated_at）が含まれている
• DB 構文が一致している（例: BIGSERIAL vs AUTO_INCREMENT）
• 既存テーブルの拡張か新規テーブルかが明確に区別されている
• 新規テーブルの場合、既存テーブルとの関係が既存の設計と整合しているか

よくある不整合:

• テーブル名が複数形（voyages）-> data-model.md は単数形（voyage）
• PK が業務キー直接（voyage_number PRIMARY KEY）-> 規約はサロゲートキー + UK
• FK が業務キー参照（REFERENCES voyages(voyage_number)）-> 規約は voyage.id 参照
• PostgreSQL 構文（BIGSERIAL）と MySQL 構文（AUTO_INCREMENT）の混在

ステップ 5: UI 設計（ビュー）との整合性

イテレーション計画の「設計 > ユーザーインターフェース > ビュー」セクションと ui_design.md を比較する。

チェック項目:

• ナビバー構造が {/ <b>CargoTracker</b> | メニュー... | [ログアウト] } 形式と一致している
• テーブルヘッダー表記が **太字** 形式と一致している（^カレット^ 形式になっていないか）
• URL パスが画面一覧の規約と一致している
• 新規画面の画面一覧エントリが定義されている
• 既存画面の拡張の場合、拡張箇所が明確に区別されている
• 検索フォームのレイアウトが既存画面と一致している
• ボタン配置・ラベルが既存画面のパターンと一致している

よくある不整合:

• 独自のナビバー構造を使用
• テーブルヘッダーの表記形式が異なる
• URL パスが未定義
• 既存画面との関係（拡張 vs 新規）が不明確

ステップ 6: UI 設計（インタラクション）との整合性

イテレーション計画の「設計 > ユーザーインターフェース > インタラクション」セクションと ui_design.md の画面遷移図・htmx パターン・フィードバック規約を比較する。

チェック項目:

• 画面遷移図に全画面の state が定義されている（URL パス・説明テキスト付き）
• バリデーションエラーの自己ループ遷移が全フォーム画面に定義されている
• 遷移方式（GET / PRG）が各遷移に明記されている
• 既存の state（航路一覧等）との遷移関係が定義されている
• htmx パターン（hx-get/hx-post・hx-target・hx-swap）が定義されている
• フィードバックメッセージ（成功・警告・エラー）とスタイル（alert-*）が定義されている
• htmx エラーハンドリング（htmx:responseError）への対応が考慮されている

よくある不整合:

• バリデーションエラー自己ループ遷移の欠落
• htmx パターンの記述がない（画面遷移図のみで動的更新方式が不明）
• フィードバックメッセージの定義がない
• 既存画面 state との遷移関係が切断されている

ステップ 7: ゴールの整合性（最終確認）

イテレーション計画全体を俯瞰し、イテレーションのゴールと各ストーリー・設計・タスクが一貫しているかを確認する。ステップ 1-6 がフォーマットおよび個別ドキュメントとの突合であるのに対し、本ステップは計画内部の論理的整合性を検証する最終関門である。

チェック項目:

• イテレーションゴール（目的・達成条件）が明確に記述されている
• 含まれる全ストーリーがゴールの達成に寄与している（ゴールと無関係なストーリーが混入していないか）
• ゴールの達成に必要なストーリーが欠落していないか
• ストーリー間の依存関係が識別され、実装順序に反映されている
• 設計セクション（ドメインモデル・データモデル・UI）がストーリーの受入基準を満たすに十分な内容か
• タスク分割がストーリーの受入基準をすべてカバーしている
• 見積もり（ストーリーポイント）の合計がチームのベロシティと整合しているか
• 前イテレーションからの持ち越し事項が反映されているか

よくある不整合:

• ゴールが抽象的すぎて達成条件が判断できない（例: 「航路管理機能を改善する」→ 具体的な完了基準がない）
• ゴールに対して過剰なストーリーが含まれている（スコープクリープ）
• 設計セクションの内容がストーリーの一部しかカバーしていない
• タスク分割が設計セクションと対応していない（設計にあるがタスクにない、またはその逆）
• ベロシティを超えるポイントが計画されている

ステップ 8: 過去レビュー指摘事項との整合性

docs/review/ 内の最新レビューファイルを確認し、前イテレーションで発見された指摘事項が今回の計画に適切に反映されているかを検証する。コードレビュー（*_review_*.md）・UI/UX レビュー（*_uiux_review_*.md）・分析レビュー（*_review_*.md）のいずれも対象とする。

チェック項目:

• docs/review/index.md で最新のレビューファイルを特定している
• 高優先度（「高」）の指摘事項がストーリーまたはタスクとして計画に含まれているか、含まれない場合は対応方針（許容 / 保留）が計画に明記されているか
• 中優先度（「中」）の指摘事項について、対応するストーリー / タスク / 対応方針が計画に記載されているか
• 前イテレーションの「IT2 対応方針」「次のステップ」「持ち越し事項」として明記された指摘が計画に引き継がれているか
• レビューで発見された受入基準の不整合（未実装フィールド等）が、当該ストーリーの受入基準の修正として反映されているか
• 技術的負債（アクセシビリティ違反、バリデーション仕様乖離等）の解消が計画に含まれているか

確認対象レビューファイルの特定方法:

1. docs/review/index.md のレビュー一覧テーブルを確認する
2. 今回計画するイテレーション番号の直前イテレーションに対応するレビューファイルを抽出する
3. 複数のレビュー種別（コードレビュー + 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 | データモデル | OK / NG | N 件 |
| 5 | UI 設計（ビュー） | OK / NG | N 件 |
| 6 | UI 設計（インタラクション） | OK / NG | N 件 |
| 7 | ゴールの整合性 | OK / NG | N 件 |
| 8 | 過去レビュー指摘事項 | OK / NG | N 件 |

### 不整合一覧（NG の場合のみ）

#### ステップ N: 〇〇との不整合

| # | 不整合内容 | 計画の記述 | 正しい記述（ドキュメント準拠） | 修正要否 |
|---|----------|-----------|---------------------------|---------|
| 1 | ... | ... | ... | 要修正 |

注意事項

• 検証は計画作成直後に実施する（開発着手前に不整合を解消する）
• 既存ドキュメントへの反映が必要な変更点は、イテレーション計画内に「注」として明記する
• イテレーション完了時に、注記された変更点を各設計ドキュメントに反映する
• 不整合を発見した場合、イテレーション計画側を設計ドキュメントに合わせて修正する（設計ドキュメントが正）