---
description: L1/L2 から L3 フェーズドキュメント（docs/l3_phases/PH-xxxx.md、機能一覧＋受け入れ条件＋Exit Criteria）を生成する。フェーズはデモ可能な縦切り（2〜4個推奨）に分割し、初回は準備フェーズ PH-0000 も自動生成する。gen-l2 の後、gen-code の前に使う。
when_to_use: 実装計画を立てたい・フェーズに分割して・機能分解したい・受け入れ条件を作って・マイルストーンを切りたい・タスクを洗い出したい・PH-xxxx を生成/再生成して、と言われたとき。英語では plan phases / break down features。コードを書くのは gen-code、フェーズ形式の split/merge は reshape-l3 を使う。
argument-hint: "[PH-xxxx] - 特定フェーズのみ生成（省略時は全フェーズ計画）"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# L3 フェーズ生成スキル

<tri_ssd_context>
Tri-SSD: L0(任意メモ docs/l0_ideas/) → L1(要件 docs/l1_requirements/vision.md) → L2(構成 docs/l2_foundation/foundation.md) → L3(フェーズ docs/l3_phases/PH-xxxx.md)。
ID形式: PREFIX-nnnn（REQ, PH, F）。番号は再利用しない（永久欠番）。
配置・分割・粒度の判断に迷ったら `${CLAUDE_SKILL_DIR}/../../docs/layer-rules.md` を読むこと。
</tri_ssd_context>

## 概要

L1/L2 をベースに、L3 フェーズドキュメントを生成する。
各フェーズは独立したファイルとして `docs/l3_phases/` に配置。

**フェーズ = 実装単位（デモ可能な縦切り）**。機能と受け入れ条件をインラインで記述。
**L3 は「完了したら腐る」情報の置き場**。実装で判明した恒常的な事実（外部仕様等）は L2 の「確認済みの前提」へ。

## 生成時の原則

<avoid_over_engineering>
- **フェーズを細かく分けすぎない**: 2〜4フェーズ程度が適切（準備フェーズ PH-0000 は数に含めない）
- 各フェーズは「デモ可能な成果物」を出せる単位にする（F 3〜7個目安）
- 受け入れ条件は1機能につき2〜5個程度（10個以上は過剰）
- 最初のフェーズは小さく、早く成果を出せる構成にする
- 詳細はコード生成時にAIが考える（ここでは概要レベル）
- 事前確認（スパイク）は「この設計で実装できるか不確実」な場合のみ設ける
</avoid_over_engineering>

## 引数

- `$ARGUMENTS` (省略可): 対象フェーズID
  - **省略**: 全体計画（複数フェーズを提案）
  - **PH-xxxx**: 特定フェーズのみを対象にする（既存なら再生成、初回実行モード中なら PH-0000 生成後にそのフェーズを新規作成）

### 使用例

```
/gen-l3                           # 全体計画（2〜4フェーズ提案）
/gen-l3 PH-0001                   # 特定フェーズを再生成
```

## 前提処理

1. `docs/l1_requirements/vision.md` を読み込み、要件を把握する
2. `docs/l2_foundation/foundation.md` を読み込み、技術スタックを把握する
3. `docs/l3_phases/` 内の既存フェーズを確認（再生成モード判定）
4. **初回実行判定**: 以下の**両方**を満たす場合のみ初回実行モード
   - アクティブな PH が0件: Glob `docs/l3_phases/PH-*.md` と `docs/l3_phases/PH-*/_phase.md`（フォルダ形式）がいずれも0件（`_archive/` 除外）
   - `docs/l3_phases/_archive/` にも PH が存在しない

   全フェーズがアーカイブ済みのケースは**初回ではない**。PH-0000 を再生成せず（重複定義になる）、次期フェーズを `next_id.py PH` の続き番号で計画する。

## 初回実行: 準備フェーズ (PH-0000)

前提処理4の**初回実行モードに該当した場合**（引数で特定 PH-ID を指定されていても同様）、
**`${CLAUDE_SKILL_DIR}/references/ph-0000-template.md` を読み**、その定義に従って準備フェーズ
`PH-0000_preparation.md` を機能フェーズより先に生成する。初回でなければこの参照ファイルは読まない。

---

## 出力フォーマット（必須）

### YAMLフロントマター（各フェーズファイル）

```yaml
---
id: PH-xxxx
status: planned          # planned | in_progress | done
requires: [REQ-xxxx, REQ-xxxx]   # このフェーズが応える要件ID
updated: YYYY-MM-DD
---
```

- `status` は gen-code が実装開始時に `in_progress`、フェーズ内の全 F が PASS になった時点で `done` へ更新する
- `requires` には機能の「対応REQ」をフェーズ単位で集約する

### 必須構造（各フェーズファイル）

**生成前に `${CLAUDE_SKILL_DIR}/references/phase-template.md` を必ず読む**。テンプレート全文と、各セクションの記入基準・AC の書き方（検証手段の使い分け・良い例/悪い例）が定義されている。

**必須**: フロントマター、目的、機能一覧（受け入れ条件付き・検証手段付き）、Exit Criteria
**省略可能**: 事前確認、複雑な機能のみ追加説明
**空のまま生成**: 検証記録、完了サマリ（見出しだけ置く。Plan と事後証跡を混ぜないため）

文体・構造化・機械契約マーカーの書式は `${CLAUDE_SKILL_DIR}/../../docs/writing-rules.md`（記載規約の SSOT）に従う。

---

## 再生成モード（既存ファイルがある場合）

### 保持するもの（上書きしない）

| セクション | 理由 |
|-----------|------|
| 受け入れ条件・Exit Criteria のチェック状態 | 進捗を保持（`[x]` を消さない） |
| 検証記録・完了サマリ | 事後証跡を保持 |
| frontmatter の status | 進捗を保持 |
| アーカイブ済みファイル | `_archive/` 内のファイルは対象外 |

### 更新するもの

| セクション | 条件 |
|-----------|------|
| 機能の概要 | L1要件が変更された場合 |
| 受け入れ条件（未チェック分） | 要件変更時 |
| 新規機能の追加 | L1に新しいREQが追加された場合 |

### 再生成時の手順

1. 既存ファイルを読み込み、チェック状態を把握
2. L1/L2との差分を分析
3. ユーザーに「何を更新するか」を確認
4. 完了済み項目は保持、未着手部分のみ更新

### フォルダ形式（split 済み）のフェーズの再生成

reshape-l3 で分割済みのフェーズ（`PH-xxxx_*/`）を再生成する場合、**同名の単一ファイルを並存生成しない**（重複定義になる）。書き込み先は gen-code と同じ規則で振り分ける:

| 更新対象 | 書き込み先 |
|---------|-----------|
| 機能の追加 | 新規 `F-xxxx_*.md` を作成し、`_phase.md` の機能一覧リストに1行追加 |
| 既存機能・AC の更新 | 該当 `F-xxxx_*.md` |
| 目的・Exit Criteria・frontmatter | `_phase.md` |

---

## 生成手順

### Step 1: 全体フェーズ計画（引数なしの場合）

1. L1の要件を機能候補に分解
2. 機能を「結合して意味のある単位」でグルーピング
3. フェーズ数を決定（2〜4フェーズ推奨）
4. ユーザーにフェーズ計画を提示して確認

<thinking_process>
フェーズ設計前に、以下を判断する：

1. **適切なフェーズ数は？**
   - 小規模（機能5個以下）: 2フェーズ
   - 中規模（機能6〜15個）: 3フェーズ
   - 大規模（機能16個以上）: 4フェーズ

2. **各フェーズの境界は？**
   - 「この時点でユーザーに見せられるか？」で判断
   - 技術的な区切りより、ビジネス価値の区切りを優先

3. **最初のフェーズに何を入れるか？**
   - 早く成果を出せる機能を優先
   - 依存関係の根幹となる機能を含める

4. **設計に不確実な前提はあるか？**
   - L2「設計判断の記録」の `（未確認…）` 印と L1 の制約・外部連携から未確認の前提を洗い出す
   - **計画全体を左右する前提**（崩れると計画を作り直すもの）→ PH-0000 の「技術前提の事実検証（スパイク）」F へ。**非初回**（PH-0000 がアーカイブ済み）の場合は、次に生成するフェーズの先頭に「技術前提の事実検証」F を置く
   - **特定フェーズだけに影響する前提** → 該当フェーズの「事前確認」節へ
   - 振り分けたら L2 の印を実際の検証場所で確定させる: `（未確認・要検証）` → `（未確認・PH-xxxx で検証）`（印と検証場所のズレを残さない）
   - いずれも結果（判明した事実）は L2「確認済みの前提」へ書く運用（作業だけを L3 に置く）
</thinking_process>

### Step 2: 機能分解とID採番

- L1の各REQを機能に分解
- 機能IDは F-nnnn 形式で採番（下記「ID採番」）
- 各機能に対応REQを紐付け、フェーズの frontmatter `requires` に集約

### Step 3: 受け入れ条件の記述

各機能に対して:
- ユーザー視点で「何ができればOKか」を記述
- 1機能につき2〜5個程度
- **コーディングエージェントが自律的に検証可能**な形で書く
- **検証手段が明確な場合は `- 検証:` サブ行を追加**（不明な場合は省略可）
- L2の「テスト・検証戦略」セクションが存在する場合、そこのツール・コマンドを活用

検証手段の使い分け（テスト/コマンド/目視）と AC の良い例/悪い例は `phase-template.md`（「必須構造」で読み込み済み）の「受け入れ条件（AC）の書き方」に従う。**目視確認は最終手段** — 自動検証で代替できないか先に検討する。

### Step 4: Exit Criteria の設定

各フェーズの完了条件を設定:
- 全機能の受け入れ条件がパスしている
- 結合テストがパスしている（必要な場合）
- デモ可能な状態になっている

### Step 5: ファイル生成

フェーズごとに独立ファイルを生成。ファイル名: `{フェーズID}_{kebab-case-フェーズ名}.md`

```
docs/l3_phases/
├── PH-0000_preparation.md    ← 初回実行時に自動生成
├── PH-0001_mvp.md
└── PH-0002_beta.md
```

---

## ID採番

ID は共有スクリプトで採番する（採番ミス防止）:

```bash
python3 "${CLAUDE_SKILL_DIR}/../../scripts/next_id.py" PH             # 次のフェーズID
python3 "${CLAUDE_SKILL_DIR}/../../scripts/next_id.py" F --count 5    # 機能IDを連続5件
```

`python3` が使えない環境（Windows の python3 は Store スタブの場合がある）では `python` / `py`。スクリプトが使えない場合は手動で（既存ID を Grep（`_archive/` 含む）で検索 → 最大 + 1 → 4桁ゼロ埋め）。

- **PH-0000** は準備フェーズとして予約（初回実行時に自動生成）
- 機能フェーズは **PH-0001** から開始（既存 PH が無ければ `next_id.py PH` は自動的に PH-0001 を返す）

## 完了後の案内

- 生成ファイルのパスを報告
- フェーズ数と機能数、TODO箇所の数を報告
- **PH-0000 を生成した場合**: 準備フェーズが含まれる旨を明記し、`/gen-code PH-0000` で環境整備から着手することを案内
- `/gen-code PH-xxxx` または `/gen-code F-xxxx` でコード生成できることを案内
- 機能数が多いフェーズ（F 5個以上目安）は `/reshape-l3` で機能単位のファイルに分割できることを案内
- フェーズの実装完了後は `/archive-l3 PH-xxxx` で完了処理できることを案内（フェーズ単位）

---

## エラーケース

| ケース | 対応 |
|--------|------|
| L1が存在しない | エラー: 「L1が見つかりません。`/gen-l1` を先に実行してください」 |
| L2が存在しない | エラー: 「L2が見つかりません。`/gen-l2` を先に実行してください」 |
| L1/L2が作成途中 | 警告: 「L1/L2が作成途中の可能性があります。続行しますか？」 |
| 指定したPH-IDが存在しない（初回実行モードを除く） | エラー: 「指定されたフェーズが見つかりません」（初回実行モード時は PH-0000 生成後に新規作成する） |