align-planning

#スキル（Skill）：計画の調整

目的 (Purpose)

タスク実行後の調整ループを通じて、プロジェクトの実行をより上位の計画に沿わせます。完了した作業からさかのぼって戦略を確認し、乖離を検出して、トップダウンの再調整案を生成します。

---

中核目標（Core Objective）

最優先目標：タスク完了後、明確な乖離分類と優先度付きの再調整アクションを含む、実行可能な計画調整レポートを生成します。

成功基準（すべて満たす必要があります）：

1. ✅ 追跡の完了：選択したモードに適用されるプロジェクト階層を通じて、完了したタスクを追跡します
2. ✅ ドリフトの分類：検出されたすべての乖離を計画ドリフトモデル（目標、要件、ロードマップ、優先順位）で分類し、各項目に影響範囲と根本原因を含めます
3. ✅ 調整案の生成：次のタスクを含む、トップダウンの再調整案リストを提示します
4. ✅ レポートの永続化：計画整合性レポートを合意済みのパスに書き込みます
5. ✅ 証拠の準備状況の評価：欠落または不十分なドキュメントを明示的に評価し、その評価を確信度に反映します
6. ✅ 安全でない書き込みの回避：マッピングが不確かな場合、または更新に破壊的な影響がある場合は、ファイル単位の変更を提案する前にユーザーの確認を求めます

受け入れテスト：チームメイトはレポートを読んで、計画が実行と整合しているか、どのような乖離があるか、次に何をするべきか、そしてその理由をすぐに把握できますか？

---

範囲の境界（範囲の境界）

このスキルが担当する内容：

• タスク後の調整評価
• プロジェクト階層をまたぐボトムアップの追跡
• ドリフト検出、影響分析、根本原因の記録
• トップダウンの再調整案
• 優先度のヒントを付けた次のタスクの提案
• 計画ドキュメントが不完全な場合の証拠準備状況の評価と適切な縮退

このスキルが担当しない内容：

• 要件の一からの書き直し（「要件を分析」を使用）
• アーキテクチャの再設計（「ソリューションを設計」を使用）
• アーキテクチャとコードの準拠性（「align-architecture」を使用）
• 新しいロードマップやマイルストーンシステムの一からの作成
• コード変更の実装
• チームの振り返りの進行（「うまくいったこと／うまくいかなかったこと」）

引き継ぎポイント：レポートの作成とレビュー後、問題の種類（要件、アーキテクチャ設計、計画、アーキテクチャ準拠性、または修正ループ）に応じて、関連するスキルに引き継ぎます。

---

使用場面（ユースケース）

• タスク後のチェックポイント：任意のタスク完了後に整合性を検証します
• マイルストーン終了レビュー：マイルストーンを完了としてマークする前に、完全な整合性チェックを実行します
• リリース準備：リリース対象を絞り込む前に、計画の乖離を検出します
• スコープ移行の診断：最近の作業が引き続き現在の目標を支えているかを調査します
• バックログの優先順位再設定への入力：証拠に基づく次のタスクの優先順位付けの指標を生成します

---

オーケストレーションのガイダンス

場面	推奨順序
日常的なタスク完了	align-planning（軽量）
マイルストーンまたはリリースゲート	align-planning（完全）→ 次にalign-architecture
計画ドリフトの疑い	align-planning
設計とコードの準拠性が必要	align-architecture （計画にも問題がある場合は、align-planning の後に実行）

計画階層の整合性が不確かな場合は、まず「align-planning」を実行します。計画アーキテクチャとコードの整合性検証の後に、「align-architecture」を実行します。

---

動作（動作）

フェーズ 0：規範の解決（v1.4 新規追加）

specs/artifact-contract.md §8 Runtime Norms Resolution Protocol の §8.2 / §8.3 / §8.5 に従って実装します。プロジェクト規範に planning-alignment artifact_type の path_pattern が宣言されている場合はプロジェクトの値を使用し、そうでない場合はスキルのデフォルト（docs/calibration/planning-alignment.md）にフォールバックします。このスキルは固定パスのガバナンス成果物であり、path_pattern のオーバーライド機構のみを使用します。

エージェントの即時実行契約

実行開始時に、以下の指示契約に従います。

You are responsible for planning alignment.

When a task is completed, perform traceback analysis to ensure planning
(goals, requirements, milestones, roadmap) is aligned with execution,
and produce a structured Planning Alignment Report.

対話ポリシー

• デフォルト：コンテキストからモードを判断します（リリース／マイルストーン／エピックの場合を除き、軽量級）。ドキュメントルートはワークスペース内のものを使用します
• 選択オプション：ユーザーが希望する場合、モードを「[軽量級][完全]」で上書きできます
• 確認：ファイル単位の変更を提案する前に確認します。不確かなマッピングがある場合は続行前に確認します（NeedsMappingConfirmation）

フェーズ 0：モードとコンテキストの解決

1. 確定的なポリシーに従ってモードを解決します：
   • ユーザーが明示的にモードを設定した場合は、それを使用します
   • そうでない場合、コンテキストに「release」、「マイルストーン終了」、または「epic-done」が含まれていれば、完全整合モードを使用します
   • それ以外の場合は軽量モードを使用します
2. ドキュメントのパスを解決します：
   • デフォルトのマッピングでは、プロジェクト-ドキュメント-テンプレートのレイアウトを使用します
   • ユーザーがパスマッピングのオーバーライドを提供した場合は適用します
   • 任意の検出：ユーザーがパスマッピングを指定しておらず、デフォルトのレイアウトも一致しない場合は、ドキュメント構造の検出を実行します（たとえば、リポジトリのルートでdocs/、docs/要件/、docs/ロードマップ*、*.mdを検索）。または、パスを確立するためにdiscover-docs-normsを提案します。想定したマッピングを報告し、明確でない場合は確認を求めます
3. 最低限のコンテキストを確認します：
   • 完了したタスクの要約
   • 少なくとも1つの追跡アンカー（要件 ID、ロードマップ項目、マイルストーン参照、または同等のもの）

フェーズ 0.5：証拠の準備状況の評価

さかのぼって追跡する前に、証拠の品質を評価します：

• 強い：選択したモードで必要なすべての階層に、規範となるドキュメントが存在します
• 弱い：一部のドキュメントは存在しますが、少なくとも1つの必須階層が補助的な証拠（イシュー／PR／コミットの説明）に依存しています
• 欠落：重要な階層を利用できず、信頼できるドリフト分類を行えません

ルール：

1. ドキュメントの欠落を、暗黙のうちに整合しているものとして扱ってはいけません。
2. 規範となるドキュメントが欠落している場合に限り、補助的な証拠を使用し、明確にラベル付けします。
3. 結論の確信度は、準備状況に応じて調整する必要があります：
   • 強 -> 高い確信度
   • 弱 -> 中程度の確信度
   • 失踪 -> 低い確信度、またはブロック

モードの定義

• 軽量モード：タスクバックログ→ロードマップ→要件
• 完全整合モード：タスクバックログ→ロードマップ→マイルストーン→要件→プロジェクト目標

このスキルの対象は計画階層のみです。アーキテクチャとコードの準拠性は「align-architecture」が担当します。

フェーズ 1：さかのぼって追跡（ボトムアップ）

1. 完了したタスクの意図、成果、目標とする結果を特定します
2. 選択した階層を上にたどり、各階層の整合性ステータスを記録します：
   • 对齐 | 部分 | 错位 | 未知
3. 各ステータスを裏付ける証拠を取得します
4. 重要なマッピングが欠落している場合は、「NeedsMappingConfirmation」に進みます：
   • 欠落しているリンクを列挙します
   • 理由を添えて候補となるマッピングを1～3件提示します
   • 続行前にユーザーの確認を求めます
   • 解決されない場合は、必要最小限の入力を示したブロッカーレポートを出力します
5. 準備状況が「弱い」または「欠落」の場合は、各階層の証拠ソースを注記します：
   • canonical（プロジェクトドキュメント）
   • 次要（イシュー／PR／コミットのコンテキスト）
   • 无

フェーズ 2：ドリフトの検出

各ドリフト項目を分類します（計画階層のみ）：

• 目標ドリフト：作業が現在のプロジェクト目標を支えなくなっています
• 要件ドリフト：要件が変更、非推奨化、または置き換えられています
• ロードマップドリフト：順序またはロードマップの前提が変化しています
• 優先順位ドリフト：現在の事業方針に対して優先順位が古くなっています

実装と設計の乖離については、「align-architecture」に引き継ぎます。

各項目について、以下を出力します：

• タイプ
• 影響範囲 -「根本原因」 -「重大度」（「低」|「中」|「高」）

フェーズ 3：調整（トップダウン）

1. 最上位から下に向かって優先順位を再導出します（目標→要件→マイルストーン→ロードマップ→バックログ）
2. 再調整アクションを生成します：
   • 優先順位の調整
   • 順序の変更
   • 依存関係の修正
   • 後続分析への引き継ぎ
3. 理由と緊急度を添えて、次のタスクを提案します
4. 規範となる計画ドキュメントの編集を提案する場合は、ファイル単位の変更案を作成する前に明示的な確認を求めます

フェーズ 4：レポートの永続化

レポートの書き込み先：

• プロジェクト規範から解決したパス（docs/ARTIFACT_NORMS.md または .ai-cortex/artifact-norms.yaml）
• デフォルト：docs/calibration/planning-alignment.md（スナップショットが明示的に要求された場合を除き、上書きします）
• またはユーザー指定のパス

人間が読めるセクションに加えて、レポートには機械可読なドリフトブロック（YAML または JSON）も含める必要があります。 レポートには、証拠の準備状況ブロックと明示的な確信度も含める必要があります。

---

入力と出力 (Input & Output)

入力（入力）

• 完了したタスクの説明と結果
• 任意のモード上書き（「軽量級」|「完整」）
• 任意のドキュメントルート／パスマッピング
• 任意のコンテキスト：リリース／マイルストーン／エピックのマーカー

出力（出力）

計画調整レポートのテンプレート

# Planning Alignment Report: <task title>

**Date:** YYYY-MM-DD
**Mode:** Lightweight | Full
**Status:** aligned | partial | misaligned | blocked
**Confidence:** high | medium | low

## Completed Task
- Summary:
- Outcome:

## Traceback Path
Task Backlog -> Roadmap -> Milestones -> Requirements -> Project Goals

## Evidence Readiness
- Readiness: strong | weak | missing
- Missing Layers:
- Secondary Sources Used:

## Alignment Status
- Goal Alignment:
- Requirement Alignment:
- Milestone Alignment:
- Roadmap Alignment:

## Drift Detected
- Type:
  Impact Scope:
  Root Cause:
  Severity:

## Impact Analysis
- Delivery impact:
- Technical impact:
- Planning impact:

## Calibration Suggestions
1.
2.
3.

## Recommended Next Tasks
1.
2.
3.

## Machine-Readable Drift

    drifts:
      - driftType: "Requirement Drift"
        severity: "medium"
        owner: "product-team"
        dueWindow: "next-sprint"
        impactScope: "Search filter acceptance criteria"
        rootCause: "Requirement updated to include keyboard navigation; task covered only click interactions"
    evidence:
      readiness: "weak"
      confidence: "medium"
      missingLayers:
        - "docs/requirements-planning/search-improvements.md"
      secondarySources:
        - "PR#142"
        - "commit:abc1234"

---

制限（制限）

厳格な境界（Hard Boundaries）

• 証拠がない場合、追跡可能性リンクを捏造しないでください
• 準備状況が「弱い」または「不足」の場合、高い確信度を主張しないでください
• ユーザーの明示的な承認なしに、計画の信頼できる情報源（目標、要件、マイルストーン、ロードマップ）をひそかに変更しないでください
• ドリフトの種類を一般的な「不整合」カテゴリにまとめないでください。入力されたドリフトの出力（目標、要件、ロードマップ、優先順位）を維持してください
• レイヤーが実際に利用できない場合を除き、完全モードでレイヤーのチェックを省略しないでください（「不明」とマークし、その理由を説明してください）
• 追跡可能な証拠に関連する理由がない場合、提案しないでください

スキルの境界（Skill Boundaries）（重複の回避）

以下は行わないでください（他のスキルで対応できます）：

• 要件の再定義ワークフロー→分析需求
• アーキテクチャの選択肢を設計するワークフロー→设计解决方案
• リポジトリレベルのオンボーディング → review-codebase、generate-standard-readme、generate-agent-entry（必要に応じて順番に実行）
• 自動テストと修正ループの実行 → run-repair-loop

停止して引き継ぐタイミング：

• 要件が無効または矛盾している → 「分析需求」に引き継ぎます
• アーキテクチャ設計の競合が主な障害となっている→「设计解决方案」に引き継ぎます
• アーキテクチャとコードの準拠性チェックが必要 → align-architecture に引き継ぎます
• 報告から修正が必要な実装上の欠陥が明らかになった → 「运行修复循环」を提案します

---

セルフチェック（Self-Check）

中核となる成功基準（すべて満たす必要があります）

• 選択したモードのトレーサビリティ確認が完了している
• 4 種類の計画モデルでドリフト項目が分類されている
• すべてのドリフトに影響範囲と根本原因がある
• トップダウンの調整アクションが提示されている
• 報告書が合意されたパスに従っている
• 証拠の準備状況と確信度が明確に報告されている
• マッピングまたは書き込みの安全性が不確かな場合、確認を求めている

プロセス品質チェック

• モードの選択が決定的なポリシーに従っている
• マッピングの不確実性によって「NeedsMappingConfirmation」が発生している
• 規範となる証拠と副次的な証拠が明確に分けられている
• すべての整合性ステータスに証拠の参照先がある
• 提案に優先順位と期限が設定されている
• 必要に応じて、隣接するスキルに明示的に引き継げる

受け入れテスト

チームメンバーは、追加の説明なしで最も重要な 1～3 件の提案を実行し、それらの優先順位が最も高い理由を説明できますか？

いいえの場合：報告書は不完全です。トレーサビリティの証拠と再調整の詳細を補完してください。

はいの場合：報告書は完成です。引き継ぎまたは実行計画に進んでください。

---

例（例）

例 1：軽量モード（通常のタスク）

コンテキスト：検索フィルター UI の動作を更新するタスクが完了しました。

モードの判定：明示的な上書きがなく、リリース／マイルストーン／エピックのマーカーもない → 軽量モード。

トレーサビリティ確認：

• タスクはロードマップ項目「search-improvements-q2」と一致しています
• 要件は引き続き有効ですが、受け入れ基準は先週変更されました
• 要件文書とロードマップ文書はいずれも規範的かつ最新であるため、証拠の準備状況は「強」です

ドリフト：

-「要件のドリフト」（中）：要件の文言がキーボード操作を含むように変更されましたが、完了したタスクではクリック操作のみが対象でした

調整：

1. キーボード操作の後続タスクを追加する
2. 関連する UI タスクのマージ前に、アクセシビリティの受け入れチェックを実施する
3. 回帰テストを可能にするため、バックログ項目の順序を変更する

例 2：完全モード（マイルストーン完了）

コンテキスト：API ゲートウェイの認証をリリースした後、「マイルストーン完了」とマークされたマイルストーンです。

モードの判定：マーカーに該当 → 完全モード。

トレーサビリティ確認：

• ロードマップとマイルストーンのマッピングは有効です
• 目標と要件は引き続き有効です
• すべての計画レイヤーに規範的な文書があるため、証拠の準備状況は「強」です

ドリフト：

• 優先順位のドリフト（高）：バックログで移行作業の優先順位が上がっていません

調整：

1. 移行エピックを現在のスプリント計画に挿入する
2. 重要度の低いゲートウェイ機能の強化を延期する
3. アーキテクチャとコードの準拠性チェックのため、align-architecture の実行を提案する

例 3：エッジケース（マッピングによるブロック）

コンテキスト：要件 ID またはロードマップリンクのない完了済みタスクです。

動作：

1. 「NeedsMappingConfirmation」を入力する
2. 確信度の注記を添えて、候補となるマッピングを提示する
3. ドリフトを分類する前に、ユーザーにマッピングの確認を求める

結果：

• ユーザーが確認した場合：通常のフローを続行する
• 確認されない場合：不足フィールドの一覧を含む「ブロック」報告書を出力する
• 規範的なマッピングが確立されるまで、確信度は「低」のままにする

---

付録：出力仕様（Appendix: Output Contract）

このスキルが生成する計画整合性レポートの機械可読部分は、以下の表の構造を満たす必要があります：

要素	形式	必須フィールド	パスのパターン
レポート本文	Markdown	front-matter（artifact_type/created_by/lifecycle）；セクション：要約 / タスクのトレーサビリティチェーン / ドリフト項目 / 再調整の提案	docs/calibration/planning-alignment.md（デフォルト；スナップショットが必要な場合は別途 -snapshot のコピーを作成）
ドリフト項目	リスト項目	id / drift_type（goal_decoupled / requirement_orphan / roadmap_stale / task_unanchored）/ artifact_path / evidence / suggested_fix	レポート本文の「ドリフト項目」セクション
証拠の準備状況	スカラー	readiness / confidence / scanned_artifacts / missing_artifacts	レポート本文の「要約」セクション
機械可読ブロック	YAML フェンス yaml drifts:	drifts[] の各項目に id/drift_type/severity/artifact_path/fix_kind を含める；evidence_readiness はトップレベルフィールド	レポート本文の末尾。plan-next による消費用