plan

実装計画スキル

概要

1つの統合された docs/specs/ 成果物の ## Decomposition セクションを作成します。これは、同じドキュメントの ## Design & Rationale セクションに記載された DR-N 要件に対応する、粒度が細かく並列実行可能なタスクを定義するものです。別ファイルはありません。トレーサビリティは1つのドキュメント内で完結します。明示的な内部トレーサビリティによって、完全な網羅性を確保します。成果物の形式は references/spec-template.md で定義されています。これに沿って作成してください。

完全な作成例については、references/worked-example.md を参照してください。

トリガー

次の場合にこのスキルを有効化します。

• ユーザーが plan コマンドを実行した場合
• ユーザーが仕様をタスクに分割するよう求めた場合
• 統合された docs/specs/ 成果物の Design & Rationale セクションを分解する必要がある場合
• ユーザーが「実装を計画して」などと依頼した場合
• Design & Rationale セクションの作成後に ideate から自動的に引き継がれた場合
• 直接実行された場合（事前に ideate が実行されていない場合）：薄め／標準の深さで、統合仕様書全体、つまり軽量／標準の Design & Rationale セクションと Decomposition の両方を一度に作成します
• --revise フラグ付きで plan-review から自動的に引き継がれた場合（ギャップが見つかった場合）

修正モード（--revise フラグ）

--revise 付きで呼び出された場合、plan-review でギャップが見つかっています。状態から .planReview.gaps を読み取り、設計を再確認し、各ギャップに対応するタスクを追加して計画ファイルを更新した後、exarchos:exarchos_workflow の action: "update" でギャップをクリアします。

修正ループの制限

計画ごとの修正は最大3回です。

3回の修正に失敗した場合：

1. planReview.revisionsExhausted = true を設定します
2. 次のように出力します："計画の修正は3回の試行後も失敗しました。設計が不完全な可能性があります。"
3. 次のように提案してエスカレーションします：設計を再検討するために ideate --redesign を推奨します

必須： テスト、計画、または TDD の手順を省略するための合理化を受け入れる前に、references/rationalization-refutation.md を参照してください。よくある言い訳とそれに対する反論、適切な対応がすべて記載されています。

検証の段階

検証の深さは影響範囲に応じて決まります。段階を上げるごとにテスト、妥当性を確認するキルプローブ、統合テストが加わります。普遍的な「必ず失敗テストを先に書く」原則ではなく、結果とテスト後の検証で判断します。各タスクでは、リスクを捉えられる範囲で最も低コストな検証を行います。

リスク層	追加するもの	理由
low	静的解析（型チェック＋リンター）で十分です	ドキュメント／設定／名前変更のみの編集は影響範囲がほぼゼロであり、テストの形式的な実施は単なる余分なコストです。
medium	対象を絞ったテスト＋check_test_adequacy キルプローブ	キルプローブは、テストファーストの唯一の実質的な保証、つまりテストが実際に失敗し得ることを、より低いコストで再確認します。すべてのコミットで先に失敗テストを書くことを義務づける代わりに、テスト後に判断します。
high	medium の内容に加え、統合テストスイート（境界では変異テストによる妥当性確認も実施）	スキーマ／型／API／共有コントラクトに関わる領域はコードベース全体にまたがります。この場合は、妥当性を確認したカバレッジと、境界をまたぐ実際の連携先との統合テストによって、コストに見合う効果が得られます。

プランナーは各タスクに riskTier（および boundaryTouching）を付与します。プランナーによる上書きがない場合、分類器が影響範囲から判定します。ディスパッチされる実装者向けプロンプトとゲートの順序は、どちらもこの付与値に応じて変わるため、検証の労力は一律のルールではなく、データに基づいて決まります。

high 層のタスクでは、結果に基づく手順を採用します（自然な順序で振る舞いとテストを書けばよく、テスト後の検証でも構いません）。

1. 新規または変更した振る舞いを対象とするテストで、そのコントラクトを明確にします
2. check_test_adequacy キルプローブで、テストが実際に失敗し得ることを確認します（ソースを元に戻し、少なくとも1つのテストが失敗することをアサートします）
3. 境界をまたぐ実際の連携先との統合テストを追加します

実装後に high 層のテスト妥当性を検証します。これはキーパーゲートです（テストを先に書く順序を強制するゲート check_tdd_compliance は廃止されました）。repoRoot: "auto" とタスクのワークツリーを指定します。プローブは、実行対象のツリーのソースを元に戻し、その後復元します。この2つのフィールドを指定しない場合、対象ツリーはサーバーのディレクトリになり、通常は自分のチェックアウトになります。また、タスクの分岐元であるブランチを baseBranch に指定します。指定しない場合、ゲートは base-missing でブロックされます。

exarchos_orchestrate({
  action: "check_test_adequacy",
  featureId: "<featureId>",
  taskId: "<taskId>",
  branch: "feature/<name>",
  baseBranch: "<branch the task forked from>",
  repoRoot: "auto",
  worktreePath: "<worktreePath>",
  riskTier: "high"
})

• passed: true — タスクのソースを元に戻すと、新規または変更したテストの少なくとも1つが失敗します。つまり、テストは空虚ではありません
• passed: false — ソースを元に戻してもテストが通ります。テストを強化してください

計画プロセス

ステップ 1：設計と根拠のセクションを分析する

統合仕様の ## Design & Rationale セクションを十分に読み込みます（ideate を実行済みの場合は、すでに記述されています。そうでない場合は、references/spec-template.md に従い、ここで thin／standard の深さで作成します）。そこから以下を抽出します。

• Problem Statement — 背景（タスクには含めませんが、スコープの判断に役立ちます）
• Chosen Approach — 実装するアーキテクチャ上の決定事項
• Requirements (DR-N) — すべてのタスクがたどるべき根拠のアンカー
• Technical Design — 実装の中核となる要件
• Integration Points — 統合および接着コードに関するタスク
• Open Questions — 解決する、または明示的に保留する決定事項

ステップ 1.5：仕様のトレーサビリティ（必須）

統合ドキュメント内に、DR-N 要件と計画したタスクを対応づけるトレーサビリティマトリクスを作成します。 手法とテンプレートについては、references/spec-tracing-guide.md を参照してください。

トレーサビリティジェネレーターを使って、マトリクスを事前に入力します。統合した docs/specs/ アーティファクトを designFile と planFile の両方に指定します（DR-N は ## Design & Rationale 領域から、タスクは ## Decomposition 領域から解析されます。どちらも同じファイル内にあります）。

exarchos_orchestrate({
  action: "generate_traceability",
  designFile: "docs/specs/<date>-<feature>.md",
  planFile: "docs/specs/<date>-<feature>.md",
  outputFile: "docs/specs/<date>-<feature>-traceability.md"
})

• passed: true — マトリクスが生成されました。「Key Requirements」列を確認して入力してください
• passed: false — 解析エラーです。仕様に想定された ##／### ヘッダーがない可能性があります

ステップ 2：タスクに分解する

各タスクは、references/task-template.md の TDD 形式に従います。

Implements: DR-N とタスク ID は仕様および task.completed イベントのフィールドです。来歴チェーンはそこからこれらを読み取ります。コードコメントに持ち込んではいけません。コードコメントでは制約を言葉で記述し、計画上の番号は示しません。詳しくは、references/task-template.md の 番号は成果物のメタデータであり、コードの一部ではない を参照してください。各タスクの検証に関する説明は、実現する動作の記述として書きます。そうすれば、実装者がその表現を反映しても、番号ではなく制約を記述することになります。

粒度のガイドライン：

• 各タスク：集中して取り組む作業として 2～5 分
• 1 つのテスト = 1 つの動作
• 大きなタスクを少数作るより、小さなタスクを多数作ることを優先します

references/testing-strategy-guide.md を使用して各タスクに testingStrategy を割り当て、エージェントが適用する検証手法を制御します。各タスクの説明とファイルパスをカテゴリ別の表に照合し、propertyTests と benchmarks のフラグを自動的に決定します。実装者に判断を委ねてはいけません。

タスクの順序：

1. まず基盤（型、インターフェース、データ構造）
2. 次にコア動作
3. その後、エッジケースとエラー処理
4. 最後に統合とグルーコード

ステップ 3：並列化を特定する

依存関係を分析し、順次実行するチェーンと、ワークツリーで同時に実行できる並列安全なグループを特定します。

ステップ 4：分解セクションを作成する

references/spec-template.md を使用して、統合仕様の docs/specs/YYYY-MM-DD-<feature>.md に ## Decomposition セクションを記述します。この ## Decomposition にはタスクの内訳を記載し、トレーサビリティは、その上にある ## Design & Rationale の DR-N ソースに照らしてこの 1 つのドキュメント内で解決します。

2 ファイルに分ける旧方式（references/plan-document-template.md → docs/plans/）は、すでに旧経路を使用して進行中のワークフローでのみ引き続き利用します。新機能では、docs/specs/ に 1 つの成果物を作成します。

ステップ 5：計画の検証

手動でチェックリストを確認するのではなく、決定論的な検証スクリプトを実行します。各スクリプトには、統合された docs/specs/ 成果物を designPath と planPath の両方として渡します。ハンドラーは設計領域から DR-N を、分解領域からタスクを解析します。

5a. カバレッジ — Design & Rationale のすべての要件がタスクに対応付けられていることを検証します（折りたたまれていた設計完全性の受け入れ条件チェックも、ここで実施されるようになりました）。

exarchos_orchestrate({
  action: "check_plan_coverage",
  featureId: "<id>",
  designPath: "docs/specs/<date>-<feature>.md",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — すべての要件が網羅されています。5a-ii に進みます
• passed: false — 不足があります。未対応の要件にタスクを追加するか、根拠を示して先送りしてください
• error — 使用方法のエラー、または仕様が空です。引数を確認してください

5a-ii. トレーサビリティチェーンの検証 — Implements: フィールドを介して、すべての DR-N 要件がタスクに対応付けられていることを検証します。

exarchos_orchestrate({
  action: "check_provenance_chain",
  featureId: "<id>",
  designPath: "docs/specs/<date>-<feature>.md",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — すべての DR-N 要件を追跡できています。5b に進みます
• passed: false — ブロック： 不足または参照先のない参照が見つかりました。続行する前に、未対応の各要件に対するタスクへ **Implements:** DR-N を追加してください。すべての DR-N 要件は、少なくとも1つのタスクに必ず対応付けてください。
• error — 設計に DR-N 識別子がありません（終了コード 2）。設計で DR-N 識別子を使っていない場合、このチェックはスキップされます（対象外）

5a-iii. D5：タスク分解の品質（助言） — 各タスクに明確な説明、対象ファイル、テストの期待事項があることを検証します。また、依存関係グラフが有効な DAG であり、並列化可能なタスクが同じファイルを変更しないことを検証します。

exarchos_orchestrate({
  action: "check_task_decomposition",
  featureId: "<id>",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — すべてのタスクが適切に分解されています。5b に進みます
• passed: false — 検出結果は ConvergenceView の D5 ゲートイベントとして記録されます。ユーザーに認識してもらうため結果を提示しますが、計画の承認をブロックしないでください
• error — 入力エラー（ファイルが見つからない、またはタスク見出しがない）です。引数を確認してください

助言： このゲートはタスク構造の品質を検証しますが、計画の承認はブロックしません。検出結果は収束の追跡用に記録されます。

5b. 仕様カバレッジチェック — 計画されたテストパスを宣言として検証します。

exarchos_orchestrate({
  action: "spec_coverage_check",
  featureId: "<feature-id>",
  planFile: "docs/specs/<date>-<feature>.md",
  repoRoot: ".",
  coveragePhase: "plan"
})

ここでは coveragePhase: "plan" を渡します。計画時点では、宣言されたテストファイルはまだ存在しないため、このチェックではディスク上に存在することを求めず、パスが正しい形式のテストパス宣言であることを検証します。このパラメーターを省略すると post-implementation にフォールバックし、宣言されたすべてのファイルが存在し、テストが実行されていることが求められます。これは計画では満たせない基準です。

• passed: true — 宣言されたすべてのテストパスが有効な事前宣言です。計画の検証は完了です
• passed: false — 宣言されたパスが正しい形式のテストパスではありません。計画内のパスを修正してください

詳しい方法については、references/spec-tracing-guide.md を参照してください。

アンチパターン

やってはいけないこと	代わりに行うこと
中・高リスクティアの動作をテストなしでリリースする	適切性を評価したテストでカバーする（テストを後から追加しても構いません）
すべてのタスクでレッド・グリーン・リファクタリングを必須にする	タスクの riskTier に応じて検証を調整する。RGR は高リスクティアで任意に選択します
大きなタスクを作成する	2～5分で完了する単位に分割する
依存関係の分析を省略する	並列化できる機会を特定する
曖昧なテストの説明	具体的に記述する：Method_Scenario_Outcome
テストが失敗することを前提にする	check_test_adequacy で失敗することを証明する（ソースを元に戻し、再実行して失敗を確認する）
「あると便利」なコードを追加する	動作に必要なものだけにする

合理化への反論

この段階的な基準は、実際にリスクの低い作業についてはすでに考慮しています。したがって、以下の言い訳は中・高リスクティアのタスクに当てはまるものであり、妥当なティア選択ではなく合理化です。

言い訳	実情
「テストするには単純すぎる」（中・高リスクティアのタスクについて）	影響範囲が広い箇所に関わるなら、そのティアは低くありません。基準が割り当てたティアでテストしてください。
「テストは後で追加します」	追加しないか、弱いテストになります。失敗できないテストは check_test_adequacy で検出されます。
「テストで作業が遅くなります」	テストのない中・高リスクティアの変更をデバッグするほうが時間がかかります。
「設計は明白です」	今のあなたには明白でも、3か月後にはそうとは限りません。

状態管理

仕様を保存する際は、成果物を記録し、workflowType に基づいてフェーズを遷移させます。feature → plan-review、refactor → overhaul-plan-review です。artifacts.plan には統合された docs/specs/ パスを設定してください。これは planArtifactExists ガードが読み取るキーであり、1つの統合ドキュメント（ideate が artifacts.spec として記録したものと同じパス）を指します。成果物とフェーズの更新は別々の呼び出しで行います。update はフェーズ以外の変更専用です。フェーズ変更には、HSM によってガードされた transition アクションを使用します。

action: "update", featureId: "<id>", updates: {
  "artifacts": { "plan": "docs/specs/<date>-<feature>.md" },
  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
}
action: "transition", featureId: "<id>", target: "<plan-review-phase>"

フェーズ遷移とガード

完全な遷移表については、@skills/checkpoint/references/phase-transitions.md を参照してください。

クイックリファレンス： plan → plan-review の遷移には plan-artifact-exists ガードが必要です。transition 呼び出しの前に、artifacts.plan に統合された docs/specs/ パスを設定してください。

スキーマの確認

パラメータスキーマを確認するには、exarchos_workflow({ action: "describe", actions: ["update", "init"] }) を使用してください。フェーズ遷移、ガード、プレイブックのガイダンスを確認するには、exarchos_workflow({ action: "describe", playbook: "feature" })（または "debug"、"refactor"）を使用してください。 オーケストレーションのアクションスキーマを確認するには、exarchos_orchestrate({ action: "describe", actions: ["check_plan_coverage", "check_provenance_chain"] }) を使用してください。

完了条件

• 設計ドキュメントを読み、内容を理解した
• 仕様のトレーサビリティ表を作成した（exarchos_orchestrate({ action: "generate_traceability" })）
• スコープを宣言した（全体、または根拠を示した一部）
• タスクを2～5分単位に分解した
• 各タスクに riskTier（および boundaryTouching）のスタンプを付与した。中／高リスクのタスクには妥当性を評価したテストを含め（テストは後から作成）、高リスクのタスクには統合スイートも追加した
• 依存関係をマッピングした
• 並列グループを特定した
• 計画の検証に合格した — exarchos_orchestrate({ action: "check_plan_coverage" }) が passed: true を返す
• 来歴チェーンを確認した — exarchos_orchestrate({ action: "check_provenance_chain" }) に合格した（ブロッキング。先に進む前にギャップを解消する必要があります）
• タスク分解を確認した — exarchos_orchestrate({ action: "check_task_decomposition" }) を実行した（参考情報。所見は提示されますが、ブロッキングではありません）
• 仕様カバレッジチェックに合格した — exarchos_orchestrate({ action: "spec_coverage_check", featureId: "<feature-id>" }) が passed: true を返す
• カバレッジのしきい値を満たした — exarchos_orchestrate({ action: "check_coverage_thresholds", featureId: "<feature-id>" }) が passed: true を返す：

exarchos_orchestrate({
  action: "check_coverage_thresholds",
  featureId: "<feature-id>",
  coverageFile: "coverage/coverage-summary.json",
  lineThreshold: 80,
  branchThreshold: 70,
  functionThreshold: 100
})

• 統合仕様を docs/specs/ に保存した（設計と根拠＋分解を1つのドキュメントにまとめる）
• 状態ファイルを更新し、artifacts.plan に統合仕様のパスを、tasks にタスクを設定した

遷移

分解が完了したら、自動的に plan-review へ進みます。適切なレビュー用フェーズへ遷移します（feature：plan-review、refactor：overhaul-plan-review）。plan-review は、設計との差分をその場で確認するレビューではなく（成果物が1つになったため）、統合成果物を対象としたディスパッチ方式の、独立したコンテキストによる敵対的な読み取り専用レビューです（DR-10）。レビュアーには {成果物＋仕様} のみを渡し（作成時の会話記録は渡しません）、凍結された designDepth に応じた深さで、計画に反論するよう促します。exarchos_orchestrate({ action: "prepare_review", scope: "plan", artifact: "docs/specs/<...>", designDepth: "<frozen>" }) を使って準備してください。

• 反論あり（ギャップあり）：.planReview.gaps を設定し、自動的に plan --revise に戻る
• 問題なし：ユーザーに提示し、承認を求める（人間による唯一のチェックポイント）
• 承認後：.planReview.approved = true を設定し、delegate を呼び出す

必須： 統合成果物に対して exarchos_orchestrate({ action: "check_plan_coverage" }) を実行してください。passed: false の場合 → 自動的に plan --revise を呼び出します。passed: true の場合 → plan-review フェーズへ遷移し、plan-review の承認後にのみ delegate を呼び出します。

Exarchos との統合

フェーズ遷移では、exarchos_workflow の set を介して workflow.transition イベントが自動的に出力されます。exarchos_event に手動で追記する必要はありません。

トラブルシューティング

問題	原因	解決方法
check_plan_coverage が passed: false を返す	設計セクションがタスクに対応付けられていない	未対応のセクションにタスクを追加するか、明示的な延期理由を追加します
spec_coverage_check が passed: false になる	計画されているテストファイルが見つからない、または失敗している	不足しているテストのスタブを作成し、計画内のファイルパスが実際のパスと一致することを確認します
generate_traceability が passed: false になる	設計ドキュメントに想定される ##／### 見出しがない	設計で標準的な Markdown 見出しが使われていることを確認します
修正ループ（3 回以上の試行）	設計と計画の間に継続的な不整合がある	planReview.revisionsExhausted = true を設定し、ideate --redesign を提案します

パフォーマンスに関する注意

• 次のステップに進む前に各ステップを完全に終えます。速度より品質を優先してください
• 変更が些細に見える場合でも、検証チェックを省略しないでください
• すべての設計セクションを少なくとも 1 つのタスクに対応付けてください。明示的な理由なしに未対応のセクションを残さないでください