plan

スキル：plan

WHAT

目的とコンテキスト

• 目的： 承認済みの SPEC を、このコードベースについて何も知らず、しかも判断が怪しい優秀なエンジニアでも正しく実行できる文書にします。overstack では、その「エンジニア」は通常、ヘッドレスで動作する安価な CLI（opencode / agy / kiro）です。この CLI はメインセッションのコンテキストを一切引き継がず、聞き返すこともできず、曖昧な箇所に出くわすと推測して黙ったままです。実測による教訓 250626：薄い brief → 納品は約 1/5。
• トリガー（使用するタイミング）：
  • SPEC（/propose）がゲートでユーザーに承認され、エージェントにタスクをディスパッチする直前。
  • 複数のステップやファイルを伴う作業、または 2 つ以上のエージェントに並行して割り当てる作業。
• 対象外： 承認済み SPEC がない場合は使用しません（先に /propose を使用）。また、1 行だけの修正には使用しません。設計や要件の確認にも使用しません（それは /propose の役割です）。

メンタルモデル

PLAN に記載されていないことは、エージェントには存在しません。これがこのスキルの原則のすべてです。

承認済み SPEC（FR-xxx、Global constraints）→ スコープ確認 → ファイル構成 → tracer bullet タスク（または expand → migrate → contract）→ 各タスク：要件 + ファイル + インターフェース + 依存関係 + 検証 + TDD の手順 → セルフレビュー → DDMMYY-<tên>-PLAN.md → orca orchestration task-create/dispatch --inject を原文のまま実行

入力と出力の契約

	フィールド	必須？	意味
入力	承認済み SPEC llmwiki/wiki/sources/draft/DDMMYY-<tên>.md	はい	## Context、## Global constraints、## Plan、## Agent Task Assignment をそのまま取得します
出力	llmwiki/wiki/sources/draft/DDMMYY-<tên>-PLAN.md	はい	PLAN の規定形式：frontmatter + ## Origin + 原文の Global constraints + ファイル構成 + 複数の ### Task N
出力	wiki/index.md の行 + wiki/log.md への追記	はい	手順 7 に従います
出力	SPEC の破綻箇所の報告	逆ゲートが有効になった場合	まとめて一度に報告し、各箇所に原因となった SPEC の文を添えます

ルールと機能

• RULE-01（必須）：PLAN に .html ファイルは不要です。PLAN は機械が読むものです。HTML は、承認時に人が見る SPEC に紐づき、/propose が生成します。R7 は -PLAN.md の分岐では図のチェックを免除します。
• RULE-02（必須）：ファイルパスは常に正確に記載し、既存ファイルを修正する場合は行範囲も添えます。
• RULE-03（必須）：コードを変更するステップには、完全なコードを必ず記載します。説明だけでは不十分です。
• RULE-04（必須）：実行コマンドは正確に記載し、期待される出力も添えます（エージェントが、どのような状態が正しい失敗で、どのような状態が成功なのかを判断できるようにします）。
• RULE-05（必須）：DRY、YAGNI、TDD、頻繁なコミット。
• RULE-06（必須）：既存のコードベースでは、現在のパターンに従います。タスク外のものをついでにリファクタリングしないでください。
• 機能：SPEC とコードベースを読み、実際のパスやシグネチャを調べます。wiki に PLAN ファイル、index、log を記録します。セルフレビューが完了するまでディスパッチしません。

失敗の境界

• 承認済み SPEC がない → cancelled、/propose に切り替えます。
• 逆ゲート（タスクに落とし込めない要件、矛盾、実現不可能な方針、関数／型／ファイルを捏造する必要がある）→ blocked：停止し、不完全な PLAN を書かず、すべての破綻箇所をまとめて一度に報告し、承認を得るため /propose に戻ります。
• プレースホルダーが残っている、またはどのタスクにも割り当てられていない FR-xxx がある → failed（R7/R18 でブロック）、その場で修正します。
• 1 行だけの修正 → このスキルは使用しません。

HOW

メインワークフロー

ステップ	種類	入力	アクション	出力／終了条件	失敗時／次の対応
W01	決定的	SPEC	承認済みの SPEC を読み、項目をそのまま取得する	SPEC の内容	承認済みの SPEC がない → 停止し、/propose
W02	判断	SPEC	スコープを確認する	1 つ以上の PLAN	サブシステムが複数ある → 分割
W03	判断	SPEC + codebase	タスクを分割する前に ## File structure を描く	ファイル一覧 + 役割	ファイル／API が存在しない → B01
W04	判断	ファイル構成	タスクを tracer bullet（または wide refactor）に分割する	タスク一覧	WIDE REFACTOR → B02
W05	判断	タスク	定型に沿って各タスクを書く（Files + Interfaces + Steps をすべて含める）	### Task N の一覧	関数／型を捏造する必要がある → B01
W06	判断	PLAN の草案	3 つの観点でセルフレビューし、その場で修正する	整った PLAN	—
W07	副作用	PLAN	ファイル + インデックス + ログを書き込む	DDMMYY-<名前>-PLAN.md	R7/R18 に阻止される → 修正して再度記録
W08	副作用	PLAN	引き継ぎ：task-create + dispatch --inject に Global constraints を含めて原文のまま渡す	ディスパッチ済みタスク	—

各ステップの詳細（W01～W08 の信頼できる情報源）：

1. 承認済みの SPEC を読む — llmwiki/wiki/sources/draft/DDMMYY-<名前>.md。次の項目をそのまま取得します：## Context、## Global constraints、## Plan（- [ ] の行）、## Agent Task Assignment。

2. スコープを確認する — SPEC が複数の独立したサブシステムを対象としている場合、複数の PLAN に分割します。各 PLAN 単体で実行可能なソフトウェアとなり、テストできる必要があります。詰め込みすぎないでください。

3. タスクを分割する前に ## File structure を描く — 作成／変更するすべてのファイルと、それぞれの役割を列挙します（1 ファイルにつき 1 つの役割。ともに変更するファイルは同じ場所にまとめます）。分解の判断はここで確定し、コーディング中には行いません。

4. タスクを TRACER BULLET に分割する — 各タスクは垂直スライスです。すべてのレイヤー（data → logic → UI/CLI）を薄く貫き、それ単体で実行・検証でき、独立してテスト可能な成果物を残します。「data レイヤー全体を作る」次に「logic レイヤー全体を作る」という「水平スライス」ではありません。水平スライスは、どのタスクも単独では実行できません。セットアップ、設定、スキャフォールディング、ドキュメントは、それらを必要とするタスクにまとめます。あるタスクをレビュー担当者が却下しても、もう一方は承認できる場合に限り、別々にします。

   明示的な例外 — WIDE REFACTOR（expand → migrate → contract）。 blast radius がコードベース全体に及ぶ機械的な変更（カラム名の変更や、共通のシンボルの型変更など）は、どの垂直スライスも正常に完了できません。1 か所を変更すると、何千もの call-site が同時にエラーになるためです。tracer bullet の定型を無理に当てはめないでください。順序は次のとおりです。

   • expand — 古い形式を残したまま、新しい形式を追加します。1 つのタスクです。古い形式が残るため、何も壊れません。
   • 段階的に migrate — call-site を新しい形式に移行し、blast radius（パッケージ単位、ディレクトリ単位）に応じて分割します。各グループを 1 つのタスクとし、expand タスクが先行条件となります。古い形式が引き続き使えるため、各グループの CI は成功します。
   • contract — caller が残っていないことを確認してから、古い形式を削除します。1 つのタスクとし、すべての migrate グループが先行条件となります。
   • 各グループ単体でも正常に完了できない場合は、それらを 1 つの統合ブランチにまとめ、最後に「integrate-and-verify」タスクを設けて、すべてのグループがそのタスクを先行条件とします。成功を保証するのは、その時点だけです。

5. 以下の定型に沿って各タスクを書く（Files + Interfaces + Steps をすべて含めること）。

6. セルフレビュー（以下の「Self-review」の項目にある 3 つの観点）を行い、その場で修正します。

7. llmwiki/wiki/sources/draft/DDMMYY-<名前>-PLAN.md に記録し、llmwiki/wiki/index.md に行を追加して、llmwiki/wiki/log.md に追記します。

8. 引き継ぎ：各 ### Task N を 1 つの orca orchestration task-create にします。dispatch --inject では、そのタスクの brief に ## Global constraints を含め、原文のまま渡します。要約し直してはいけません。要約は context が失われる原因になります。

ブランチ

ID	種類	条件	動作	スキップ／失敗	再合流
B01	recovery	逆ゲート：逆ゲートの項目にある停止条件が発生	停止し、すべての問題箇所をまとめて1回だけ報告し、/propose に戻って SPEC を修正して再承認を受けます	—	W01（SPEC の再承認後）
B02	conditional_required	コードベース全体に影響する機械的な変更	ワイドリファクタ：タスクを拡張 → 移行バッチ（拡張によってブロック） → コントラクト（すべてのバッチによってブロック）。バッチが単独で成功しない場合は、統合ブランチと integrate-and-verify タスクを実施します	—	W05
B03	conditional_required	SPEC が複数の独立したサブシステムを含む	複数の PLAN に分割し、それぞれ単独で実行・テストできるようにします	—	各 PLAN について W03

検証と停止

確定事項：R7 はプレースホルダーをブロックします（書き込み時＋コミット時）。R18 はどのタスクにも割り当てられていない FR-xxx をブロックします。R9／R2 は frontmatter／## Origin の不足をブロックします。各タスクの **Verify:** 行は、終了コードが 0 のコマンドです。要レビュー事項：3つの観点によるセルフレビュー（SPEC の網羅性、プレースホルダー、型／名前の一貫性）。W08 の後、または B01 の発生時に直ちに停止します。

例

• 成功例： 承認済みの SPEC DDMMYY-export-csv.md に FR-001..FR-003 がある場合 → **Thoả:**、正確なパスを示す **Files:**、Consumes／Produces を示す **Interfaces:**、Verify 行に pytest tests/test_export.py -q、Step 1–5 TDD を含む tracer bullet タスクを3つ作成 → DDMMYY-export-csv-PLAN.md ＋ index ＋ log に記録 → Global constraints を添えて各タスクを原文のままディスパッチします。
• 境界／失敗例： File structure を宣言する際に、## Approaches で選択した API が存在しないことが判明し、さらに FR-002 が Global constraints と矛盾している場合 → 停止します。中途半端な PLAN は書かず、原因となった SPEC の記述とともに両方の問題をまとめて報告し、/propose に戻って再承認を受けます。

参考 — PLAN のひな形

必須ヘッダー（frontmatter と ## Origin は省略できません — ファイルは wiki/sources/draft/ にあるため、frontmatter がないと R9 がブロックし、## Origin がないと R2 がブロックします）：

---
type: draft
title: <tên>-PLAN
status: proposed
timestamp: YYYY-MM-DD
task: T-YYMMDD-NN        # cùng task-id với SPEC
---

# <Tên> — PLAN thi hành

**Goal:** <một câu: cái này xây ra cái gì>
**Architecture:** <2-3 câu: cách tiếp cận>
**Tech stack:** <ngôn ngữ, lib, test runner, version>
**SPEC nguồn:** `wiki/sources/draft/DDMMYY-<tên>.md` (đã duyệt <ngày>)

## Origin
- **SPEC:** `wiki/sources/draft/DDMMYY-<tên>.md`
- **Commit:** _(verify-before-commit điền)_

## Global constraints
<chép NGUYÊN VĂN từ SPEC — sàn version, giới hạn dependency, luật đặt tên, gate trước push.
 Mỗi task ngầm mang theo section này.>

## File structure
- Tạo `path/chính/xác.py` — <trách nhiệm duy nhất của file>
- Sửa `path/có/sẵn.py` — <đổi gì>

各タスク：

### Task N: <tên>

**Thoả:** FR-001, FR-003

**Files:**
- Tạo: `đường/dẫn/chính/xác.py`
- Sửa: `đường/dẫn/có/sẵn.py:123-145`
- Test: `tests/đường/dẫn/test_x.py`

**Interfaces:**
- Consumes: <dùng gì từ task trước — chữ ký chính xác>
- Produces: <task sau dựa vào cái gì — tên hàm, kiểu tham số, kiểu trả về>

**Depends:** Task 1, Task 3   
**Verify:** `pytest tests/x.py -q`   

- [ ] **Step 1: viết test fail**

```python
def test_hanh_vi_cu_the():
    assert ham(dau_vao) == ket_qua_mong_doi
```

- [ ] **Step 2: chạy cho THẤY nó fail**

Chạy: `pytest tests/đường/dẫn/test_x.py::test_hanh_vi_cu_the -v`
Mong đợi: FAIL — `NameError: name 'ham' is not defined`

- [ ] **Step 3: code tối thiểu cho pass**

```python
def ham(dau_vao):
    return ket_qua_mong_doi
```

- [ ] **Step 4: chạy lại — PASS**

Chạy: `pytest tests/đường/dẫn/test_x.py::test_hanh_vi_cu_the -v`
Mong đợi: PASS

- [ ] **Step 5: commit**

```bash
git add tests/đường/dẫn/test_x.py src/đường/dẫn/x.py
git commit -m "feat: <việc cụ thể>"
```

**Thoả:** が必須である理由： SPEC は、各要件に FR-001、FR-002…という安定した ID を割り当てます。各タスクで担当する ID を宣言することで、「SPEC をすべて網羅しているか」というセルフレビューを目視確認だけで済ませず、grep 可能なデータにできます。また、どのタスクにも割り当てられていない FR-xxx があれば、R18 がブロックし、漏れている ID を正確に出力します。2つのタスクの間で要件が抜け落ちるのは、どんな計画でも最も見落とされやすいエラーです。エージェントが不完全な成果物を納品したとき、あるいはさらに悪いことに、ユーザーが使ったときに初めて明らかになります。

複数のエージェントがいる場合に Interfaces が必須である理由： 実行するエージェントに見えるのは自分のタスクだけです。シグネチャを宣言しないと、並行して作業する2つのエージェントが異なる関数名を付けてしまい、統合部分が壊れます。これはリスクではなく、確実に発生するエラーです。

参考 — プレースホルダー禁止 — これは未完成の PLAN ではなく、壊れた PLAN です

R7 は書き込み時とコミット時にブロックします。以下は決して書かないでください。

• TBD、TODO、「後で記入」、「詳細は後で」
• 「適切にエラーを処理する」／「バリデーションを追加する」／「エッジケースに対応する」—「適切に対応する」ではなく、何をするかを書いてください
• 実際のテストコードを示さずに「上記のテストを書く」
• 「Task N と同様」 — コードをそのまま書き写してください。エージェントは順不同でタスクを読むことがあり、各エージェントに渡されるのは自分のタスクだけです。
• 何をすべきかだけを説明し、どのように行うかを示さない手順（コードを変更する手順には、必ずコードを含めてください）
• どのタスクでも定義されていない関数／型／メソッドへの言及

参考 — セルフレビュー

書き終えたら、視点を新たにして見直し、その場で修正します。2回目のレビューは不要です。

1. SPEC の網羅性 — SPEC の各要件を確認し、どのタスクが実装するかを示します。漏れがあればタスクを追加します。
2. プレースホルダーの確認 — 上記の項目にあるパターンを正確に検索します。
3. 型／名前の一貫性 — 後続タスクで使う関数名、シグネチャ、フィールド名が、先行タスクで定義したものと一致しているか確認します。Task 3 の clearLayers() が Task 7 で clearFullLayers() になっているのはバグです。

リファレンス — 逆ゲート — /plan は SPEC を却下できます

PLAN を書くことこそ、SPEC の誤りを発見する方法です。実際のファイルパスと関数シグネチャを明記する段階になると、実現不可能な設計が明らかになります。審査ゲートを通過した後に問題が発覚したなら、ユーザーは構築できないものを承認してしまったということです。ゲートが機能していません。

中途半端な PLAN の作成を中断し、先へ進まないでください。次のいずれかに該当する場合：

• SPEC の要件を、実行可能なタスクに対応付けられません。
• SPEC の項目同士が矛盾している、または ## Global constraints と矛盾しています。
• ## Approaches で選択した方法が実現不可能だと判明しました（ファイルが存在しない、API がない、制約によって妨げられる）。
• plan を「書面上で実行可能」にするために、SPEC に記載のない関数、型、ファイルをでっち上げる必要があります。

対処方法：問題がある箇所をすべてまとめて、一度に報告してください（一つずつユーザーに報告して中断しないでください）。各箇所には、その原因となった SPEC の該当箇所を正確に添えてから、/propose に戻って SPEC を修正し、再度承認を受けてください。問題のある SPEC に基づいて書かれた PLAN は、PLAN がないよりも悪いものです。自信たっぷりな様子でエージェントに誤りを与え、安価なエージェントはそのまま実行してしまいます。