milestone-planning

マイルストーン計画（Ultraplan）

複雑なタスクをマイルストーンに分解するため、3つの手順で進めます。まずコードベースを広範囲に並列調査し、次に調査で判明した内容に基づいてマイルストーンのDAGを作成し、最後にその草案を批判的なレビュアーのパネルに提出し、反論に耐えられるまでラウンドを重ねます。

基本原則

マイルストーンは、長期にわたる実行の単位です。マイルストーンの分解が不適切だと、何日もの無駄な作業につながります。それを防ぐのは、次の2つです。

• 根拠。 草案は、並列調査で収集した実際のコードベースの証拠に基づいて作成します。コードがどうなっているかを推測して作るものではありません。
• 批判的な検証。 独立したレビュアーが草案を崩すことだけに専念し、実行段階で大きなコストをかける前に問題を見つけます。

レビュアーが攻撃するには、具体的な成果物が必要です。そのため、批評より先に草案を作成します。「問題をレビューする」では提案が生まれますが、「この草案を崩す」では問題点が見つかります。

必須ゲート

1. 草案作成前に調査する。 草案をまとめる前に、並列調査エージェントを実行します。すべてのマイルストーン境界には、調査で得た証拠を引用する必要があります。実際のコードベースに根拠のない境界は、判断ではなく仮定です。
2. 各ラウンドのすべてのレビュアーを並列で実行する。 Agent ツールを使い、1つのメッセージで全レビュアーを同時に実行します。順次レビューは禁止です。
3. すべてのレビュアーに、問題概要と草案の全体を渡す。 レビュアーごとに内容を絞り込んだり、一部を切り出したりしてはいけません。
4. レビュアーに、互いの批評を見せてはいけません。 ラウンド内の独立性があってこそ、レビュアー間の意見の一致に意味が生まれます。
5. すべての批評に明示的に対処する。 各指摘を批評解決ログに原文どおり記録し、「採用」（草案を修正し、修正内容を記載）または「却下」（証拠に基づく理由を記載）とします。指摘を黙って無視するのは、計画上の失敗です。
6. 批評が出なくなるまで続ける。 修正後の草案に対して、新しいレビュアーを招集して再度レビューを実施します。1ラウンド全体で新たな構造的またはブロッキングの指摘がゼロになったときのみ、草案を確定します。上限は3ラウンドです。3ラウンド目の後もブロッキングの指摘について意見が割れている場合は、双方の見解を示してユーザーにエスカレーションします。
7. すべてのマイルストーンに、二値で判定できる成功基準を設定する。 「正しく動作する」は基準になりません。各基準は、コマンドを実行するかコードを読むことで、達成・未達成を判定できる必要があります。これは、plan-crafting の受け入れ基準ルールと同じ基準です。
8. マイルストーンの依存関係はDAGを形成する必要がある。 循環依存は計画の失敗です。すべてのマイルストーンに明確なトポロジカル順序が必要です。
9. 些細なタスクのためにマイルストーンを作成しない。 1回の plan-crafting サイクル（タスク数が約8未満）で解決できる場合は、plan-crafting を直接使うようユーザーに伝えます。

使用する場面

• ユーザーが複雑で、複数日にわたるタスクを提示した場合
• 長期実行用ハーネスでマイルストーンへの分解が必要な場合
• ユーザーが「マイルストーンを計画して」「これをマイルストーンに分解して」「ultraplan」と依頼した場合
• タスクに複数の独立した実装フェーズが明らかに必要な場合

使用しない場面

• 1日で完了するタスク（plan-crafting を直接使います）
• 実装手順が約8未満のタスク
• マイルストーンがすでに定義されており、ユーザーが実行を求めている場合（long-run を使います）
• 作業範囲がまだ曖昧な場合（先に clarification を使います）

入力

このスキルでは、入力として明確な問題の説明が必要です。次のいずれかを使用できます。

1. clarification スキルで作成した Context Brief ファイル（推奨）
2. ユーザーからの直接的で詳細な依頼（目標、範囲、制約を含める必要があります）

入力が曖昧な場合は、先に clarification スキルに戻ります。

プロセス

フェーズ 1：問題の整理と広範な調査

1. 入力（コンテキスト概要またはユーザーのリクエスト）を読みます
2. 目標、範囲の境界、技術的制約、成功基準を特定します
3. 並列で調査エージェントを起動します。それぞれ異なる観点を持つ読み取り専用の Explore サブエージェントを複数、同時に実行します。
   • アーキテクチャとインターフェース： 作業が影響するモジュール、境界、契約、および従うべき既存のパターン
   • 依存関係とデータフロー： 依存関係、共有状態（DB スキーマ、設定、グローバル変数）、外部システムとそのセットアップ要件
   • 検証環境： E2E テスト、統合テスト、テストスイート、CI チェック — 検証戦略の作成に役立てます
   • 規約と履歴： 命名規則と構造上の規約、最近の関連変更、類似作業の過去の試み 問題に応じて、タスク固有の観点を追加します（データ関連の作業ではスキーマ／マイグレーションの観点、セキュリティに関わる作業では認証／権限の観点、API の変更ではクライアント互換性の観点など）。
4. 問題概要を作成します。自己完結型にし、ドラフトの作成者とすべての批評者が受け取れるようにします。

## Problem Brief

**Goal:** [What must be achieved]

**Scope:**
- In: [What is included]
- Out: [What is explicitly excluded]

**Technical Context:**
[Relevant architecture, existing code, constraints]

**Exploration Digest:**
[Key findings per lens, with file references — this is the evidence base
 the draft cites and the critics check against]

**Constraints:**
[Time, compatibility, dependencies, performance requirements]

**Success Criteria:**
[Binary-decidable outcomes]

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact command to run the verification]
- **What it validates:** [what passing this verification proves]

検証環境の調査： 計画作成と同じ調査順序（E2E → 統合テスト → 検証スキル／エージェント → テストスイート → ビルド＋Lint）を使い、結果を検証戦略のセクションに記録します。検証環境が存在しない場合、長時間実行時の統合検証マイルストーンの計画作成フェーズで、タスク 0 として環境を構築します。

フェーズ 2：分解案の作成（二つの骨組みを作成してから、一つのドラフトを作成）

一つのドラフトだけを反復して作成すると、その後の各ラウンドが最初の構成に固定されます。批評者は細部を攻撃し、「不足がなくなるまで」続けるループで磨けるのは、与えられた骨組みだけです。これを避けるには、多様な初期案を用意します。批評より先に二つのドラフトを作成します。

1. 二つのドラフト作成エージェントを並列で起動し、それぞれに問題概要の全体と調査概要を渡して、異なる構成原則を採用させます。
   • 骨組み A — インターフェース優先： コンシューマーより先にコントラクトとインターフェースを定義する順でマイルストーンを並べます。境界はアーキテクチャマップに従います
   • 骨組み B — リスク優先： リスクの高い統合や曖昧さの大きい要件を早期に検証する順でマイルストーンを並べます。境界は障害モードに従います
2. 比較して DRAFT v1 をまとめます： メインエージェントがより優れた骨組みを選び、もう一方の優れた要素を取り入れます。選択と理由を解決ログの冒頭に記録します（「骨組み：B。理由は……。A の M2／M3 の分割を取り入れた」など）。

ドラフトには完全なマイルストーン形式（フェーズ 6 を参照）を使い、DRAFT v1 と明示します。

各マイルストーンには、以下を記載する必要があります。

• 名前、目標（1 文）
• 成功基準（二値で判定可能 — ハードゲート 7）
• 依存関係（先に完了が必要なマイルストーン）
• 影響するファイル（依存関係の調査に基づく）
• リスク／工数／ユーザー価値／中止ポイント
• 根拠： この境界の妥当性を裏付ける調査概要の調査結果

根拠欄が空のマイルストーンは推測です。さらに調査するか、隣接するマイルストーンに統合してください。

フェーズ 3：敵対的クリティックパネル

ドラフトに対してクリティックパネルを実行します。すべてのクリティックを、単一のメッセージで同時に、run_in_background: true、worktree の分離なし（クリティックは読み取り専用）で実行してください。

パネルの構成 — 常に 4 人のコアクリティック：

1. 隠れた複雑さのクリティック — 「Small」マイルストーンを Large にしてしまう統合ポイント、エッジケース、データ移行、後方互換性など、工数見積もりに異議を唱えます。見積もり自体の前にスパイクが必要なコンポーネントも指摘します。
2. 依存関係と順序のクリティック — DAG に異議を唱えます。欠落している依存関係のエッジ、並列グループ内のファイル競合、順序づけられていないマイルストーンが変更する共有状態、定義するマイルストーンより先に使われるインターフェース、セットアップ手順のない外部依存関係を指摘します。
3. 検証可能性のクリティック — 成功基準に異議を唱えます。解釈が必要で判定を二値化できない基準、実施順が来ても独立して検証できないマイルストーン、どの基準でも実施されないマイルストーン間インターフェースを指摘します。
4. 統合とリスクのクリティック — 順序づけに異議を唱えます。最もリスクの高い統合が最後まで先送りされていること、最も曖昧な要件に最後に取り組んでいること（修正コストが最も高いタイミング）、システムを壊れた状態にするマイルストーン、やり直しのコストが高いのに規模が大きすぎるマイルストーンを指摘します。

さらに、課題の性質に応じて最大 2 人のタスク固有クリティックを選びます。候補：価値と順序づけ（早期にユーザーが価値を実感できること、最小限の実用的な最初のマイルストーン、中止の判断点）、移行と互換性、セキュリティとアクセス、パフォーマンス。選択理由を解決ログに 1 行で記載してください。

クリティックのプロンプトテンプレート（パネル定義から {LENS}、{LENS_FOCUS} を埋め、Problem Brief とドラフトを全文コピーしてください）：

You are the {LENS} critic reviewing a draft milestone decomposition.
Your job is to find the ways this draft fails during execution.
You are not here to be agreeable — an easy approval from you is
a defect in the process.

## Problem Brief
{PROBLEM_BRIEF}

## Draft Milestone DAG (v{N})
{DRAFT}

## Your Task

Attack the draft strictly from your lens: {LENS_FOCUS}

Rules:
- Every finding must be concrete: name the milestone, quote the draft
  text you are attacking, and state the failure scenario during
  execution. Check claims against the Exploration Digest — a draft
  assertion that contradicts the digest is automatically a finding.
- Assign each finding a severity:
  - **Structural:** the decomposition's fundamental shape is wrong —
    wrong unit of decomposition, wrong ordering philosophy, or a
    missing phase that no milestone-level edit can add. Use only when
    revision cannot fix it; a Structural finding must include a 3-5
    line sketch of the alternative shape.
  - **Blocking:** execution will fail, produce the wrong thing, or
    require redoing a completed milestone
  - **Concern:** elevated risk that needs a stated mitigation
  - **Nit:** improvement, safe to ignore
- Do not propose a full alternative decomposition — attack this one.
  The only exceptions: the "smallest fix" per finding, and the 3-5
  line shape sketch required for a Structural finding.
- If you find nothing Blocking, earn it: list the attacks you attempted
  and why the draft survived each one.

## Output Format

For each finding:
- **[Severity] Finding:** [one sentence]
- **Where:** [milestone ID(s) + quoted draft text]
- **Failure scenario:** [what concretely goes wrong during execution]
- **Smallest fix:** [minimal change to the draft that removes the failure]

If nothing Blocking: list attempted attacks and why each failed.

クリティックの失敗時の対応：

1. **タイムアウトまたはエラー：**失敗したクリティックを、同じプロンプトで 1 回再実行します。再度失敗した場合は、そのクリティックなしで進め、解決ログに欠落した観点を記録します。
2. **出力が空、または不十分：**指摘も試みた攻撃のリストも返さないクリティックは、役割を果たしていません。1 回再実行します。
3. **最小限必要なパネル：**各ラウンドで少なくとも 3 人のクリティックが正常に実行される必要があります。3 人未満の場合は停止し、ユーザーに報告します。

フェーズ 4：修正ループ（指摘がなくなるまで批評）

1. **すべての指摘をそのまま批評解決ログに記録します。**要約したり、表現を和らげたりしてはいけません。

| # | Critic | Severity | Finding (verbatim) | Resolution | Rationale / Draft change |
|---|--------|----------|--------------------|-----------|--------------------------|
| 1 | Dependency | Blocking | "M3 consumes the API defined in M4..." | Accepted | Reordered: M4 now precedes M3 |
| 2 | Complexity | Concern | "M2's migration effort is Small but..." | Accepted | M2 split into M2a (spike) + M2b |
| 3 | Verifiability | Blocking | "M5 criterion 'UX feels responsive'..." | Accepted | Rewritten: "p95 interaction latency < 100ms in the perf test" |
| 4 | Integration | Nit | "..." | Rejected | Digest shows the interface is already exercised by e2e suite |

2. **構造上の指摘があれば、修正ではなく再ドラフトを行います。**構造上の指摘を受け入れる場合は、フェーズ 2 に戻ってドラフトを再構成します。指摘の構成スケッチと未使用のスケルトンを入力として使用します。計画セッションあたりの再ドラフトは最大 1 回です。2 回目の構造上の指摘を受け入れる場合、問題の枠組み自体に問題があるため、ユーザーにエスカレーションしてフェーズ 1 を再検討します。
3. 受け入れた修正をすべて適用してドラフトを修正します（v2、v3、…）。
4. **このラウンドで構造上またはブロッキングの指摘があった場合は、修正版に対して新しいクリティックラウンドを実行します。**前のラウンドの記憶がない新しいインスタンスを使います。以前の批評を覚えているクリティックは、新しいドラフトを攻撃する代わりに古い批評に固執するためです。
5. **終了条件：**新たな構造上またはブロッキングの指摘がゼロのラウンドが完了したら、ドラフトを確定します。未解決の懸念事項については、該当するマイルストーンの Notes に緩和策を記載する必要があります。軽微な指摘は任意です。
6. **ラウンド上限：**最大 3 ラウンドです（再ドラフトを行った場合はカウントを 1 回だけリセットします）。3 ラウンド後もブロッキングの指摘に異議が残る場合は、クリティックの指摘とドラフトの反論を、どちらもそのままユーザーに提示します。

フェーズ 4.5：統合検証マイルストーン

ドラフトの確定後、メインエージェントは DAG の最後のマイルストーンとして、統合検証マイルストーンを自動的に追加します。このマイルストーンは構造上の保証であり、クリティックはその存在について意見できません。

### M_final: Integration Verification

- **Goal:** Validate that all milestones work together as a complete system
- **Success Criteria:**
  - [ ] Highest-level project verification passes (command from Verification Strategy)
  - [ ] All milestone success criteria remain met after full integration
  - [ ] Full test suite passes — no regressions in pre-existing functionality
  - [ ] Cross-milestone interfaces are exercised end-to-end
- **Dependencies:** ALL other milestones
- **Files:** None (read-only verification — no new code)
- **Risk:** Medium (integration issues between independently-verified milestones)
- **Effort:** Small (verification only, no implementation)
- **User Value:** Confidence that the system works as a whole, not just per-milestone
- **Abort Point:** No (this is the final gate)

フェーズ 4.6：DAG の独立検証

Integration Verification Milestone を追加した後、メインエージェントはユーザーに提示する前に、DAG の全体構造を独立して検証します。批評者がすべてを見つけたと想定してはいけません。

1. **循環依存の確認：**各マイルストーンの依存関係チェーンをたどります。あるマイルストーンが別のマイルストーンの祖先かつ子孫でもある場合、DAG は無効です。ドラフトを修正し、修正内容について Dependency & Ordering の批評者を再実行します。
2. **並列マイルストーンのファイル競合確認：**依存関係のないマイルストーンでは、「影響を受けるファイル」のリストが重複していない必要があります。重複がある場合は、依存関係のエッジを追加するか、ユーザーの判断を仰ぎます。
3. **孤立マイルストーンの確認：**最初のマイルストーンを除き、すべてのマイルストーンに少なくとも 1 つの依存関係があるか、理由を添えて独立して並列実行可能と明示されている必要があります。
4. **基準の確認：**すべてのマイルストーンには、二者択一で判定可能な成功基準が少なくとも 2 つ必要です。解釈が必要な基準は、提示前に書き直します。

フェーズ 5：ユーザーによるレビューと確定

これは長時間実行フロー全体で唯一の承認ゲートです。ここでユーザーが計画を確定した後は、long-run は追加の承認待ちなしですべてのマイルストーンを実行します。

**マイルストーン数のガード：**推奨数は 3～7 です。7 を超える場合は、「この計画には N 個のマイルストーンがあります。問題を別々のプロジェクトに分割すべきか検討してください。」と警告します。10 を超える場合は、続行するためにユーザーの明示的な承認が必要です。

1. 確定したマイルストーン計画を提示します
2. 批評の解決ログを表示します。ユーザーは、批評者が何を指摘し、各指摘がどのように解決されたかを確認できる必要があります
3. 並列化を含む実行順序を表示します
4. マイルストーン数を表示し、該当する場合は数のガードに関する警告も表示します
5. ユーザーに承認、変更、または却下を求めます
6. 承認された場合：すべての成果物をハーネスの状態ディレクトリに保存します
7. 変更が要求された場合：変更を適用し、影響を受ける批評者を再実行してから再提示します
8. 却下された場合：更新された制約とともにフェーズ 1 に戻ります

フェーズ 6：マイルストーンの成果物を保存

docs/engineering-discipline/harness/<session-slug>/
├── state.md                      # Master state file
├── milestones/
│   ├── M1-<name>.md              # Individual milestone definition
│   ├── M2-<name>.md
│   └── ...
└── planning/
    ├── problem-brief.md          # includes Exploration Digest
    ├── draft-v1.md ... draft-vN.md
    ├── critiques/
    │   ├── round-1-complexity.md
    │   ├── round-1-dependency.md
    │   └── ...
    └── resolution-log.md         # Critique Resolution Log, all rounds

state.md の形式：

# Long Run State: [Session Name]

**Created:** YYYY-MM-DD HH:MM
**Last Updated:** YYYY-MM-DD HH:MM
**Status:** milestone-planning-complete | executing | paused | completing | completed | failed

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact verification command]
- **What it validates:** [what passing proves]

## Milestones

| ID | Name | Status | Attempts | Dependencies | Plan File | Review File |
|----|------|--------|----------|-------------|-----------|-------------|
| M1 | [name] | pending | 0 | — | — | — |
| M2 | [name] | pending | 0 | M1 | — | — |
| M3 | [name] | pending | 0 | M1, M2 | — | — |

Status values: pending | planning | executing | validating | completed | failed | skipped
Attempts: number of plan-execute-review cycles attempted (incremented at each Step 2-3 start)

## Execution Log

| Timestamp | Event | Details |
|-----------|-------|---------|
| YYYY-MM-DD HH:MM | milestones-locked | N milestones approved by user |

個別のマイルストーンファイル（M1-.md）の形式：

# Milestone: [Name]

**ID:** M1
**Status:** pending
**Dependencies:** [None | M1, M2, ...]
**Risk:** [Low/Medium/High]
**Effort:** [Small/Medium/Large]

## Goal

[One sentence goal]

## Success Criteria

- [ ] [Binary-decidable criterion — answerable met/not-met by command or code inspection]
- [ ] [Binary-decidable criterion]
- [ ] [Binary-decidable criterion]

## Files Affected

- Create: [files to create]
- Modify: [files to modify]

## User Value

[What the user sees/can test after this milestone]

## Abort Point

[Yes/No — can user stop here and have something useful?]

## Notes

[Mitigations for open Concerns from the critique rounds; special considerations]

アンチパターン

アンチパターン	失敗する理由
具体的なドラフトではなく、問題の説明を批評する	指摘ではなく提案が生まれ、実行するまで衝突が表面化しません
一度だけドラフトを作成し、修正は一度しか行わない	修正ラウンドでは初期の骨格を磨くだけで、そこから抜け出せません。骨格を 2 つ用意し、Structural のエスケープハッチを設けているのは、まさにこのためです
調査せずにドラフトを作成する	マイルストーンの境界が思い込みになり、批評者は根拠に照らして主張を確認できません
批評者を順番に実行する	時間を無駄にします。批評者は設計上、互いに独立しています
解決する前に批評を要約したり、表現を和らげたりする	ドラフト作成者の偏りを通して指摘をふるいにかけてしまいます。ログには原文を記録します
ドラフトを変更したり反論したりせずに、指摘を「対処済み」とする	実行中にその指摘が再浮上し、数分ではなく数日のコストがかかります
ラウンドをまたいで同じ批評者インスタンスを再利用する	改訂されたドラフトを批評する代わりに、以前の批評に引きずられます
解釈が必要な基準を受け入れる	完了を検証できず、「完了」の判断が主観的になります
大きすぎるマイルストーンを作成する（各 12 タスク超）	1 回の計画作成サイクルを超過し、コンテキストが失われるリスクがあります
小さすぎるマイルストーンを作成する（各 1～2 タスク）	計画作成、run-plan、review-work のオーバーヘッドが作業そのものを上回ります
ユーザーの承認なしに 10 個を超えるマイルストーンを作成する	マイルストーンごとにリスクが積み重なり、プロジェクトの分割が必要になる可能性が高いです
ユーザーが確定承認を省略できるようにする	これが唯一の承認ゲートです。省略すると、未レビューの計画に基づく数日間の無人実行につながります

最小チェックリスト

• 草案の作成前に、並行調査エージェントを起動している
• 調査ダイジェストと検証戦略を含む問題概要を作成している
• 独立した骨子を2つ作成している（インターフェース優先、リスク優先）。根拠を記録したうえで DRAFT v1 を作成している
• 草案の DAG では、各マイルストーンについて調査の根拠を引用している
• 各ラウンドで、すべての批評担当者を並行して（単一のメッセージで）起動している
• すべての批評を逐語的に記録し、対応している（草案を変更して受け入れるか、理由を添えて却下する）
• 最終ラウンドで新たなブロッキング指摘がゼロになっている（または、異議をユーザーにエスカレーションしている）
• すべてのマイルストーンに、二値で判定可能な成功基準がある
• マイルストーン DAG に循環依存関係がない
• 統合検証マイルストーンを最後のマイルストーンとして追加している
• ロック時に、ユーザーがマイルストーン計画を承認している
• すべての成果物をハーネスの状態ディレクトリに保存している

移行

マイルストーン計画が完了したら：

• 実行を開始する場合 → long-run スキルへ
• 曖昧さが見つかった場合 → clarification スキルに戻る
• マイルストーンを設定するほど大きくないタスクの場合 → plan-crafting を直接使用する

このスキル自体は、次のスキルを呼び出しません。マイルストーン計画を提示し、次のステップをユーザーに選んでもらって終了します。