Issue Driven Development (IDD)

このスキルは AgentVillage プロジェクトの開発フローをガイドする。

サブコマンド: idd create

引数が create で始まる場合はこのフローへ進む。残りの引数（あれば）は要求の最初のヒントとして扱う。

目的

対話ベースで要求を深掘りし、仕様として十分に整理された GitHub Issue を作成する。 Issue には「何を・なぜ・受け入れ条件」を記載する。実装方針は不要（それは後の Phase 4 で決める）。

フロー

[C-1] ヒアリング（対話で要求を整理）
[C-2] Issue ドラフト提示    ← 確認
[C-3] Issue 作成 + Ideas.md 追記

C-1 ヒアリング

ユーザーの入力から以下の3点が揃っているか確認し、足りない点だけ追加で質問する:

1. 何を — 追加/変更したい機能・動作の概要
2. なぜ — 背景・動機・解決したい問題
3. 受け入れ条件 — 「これができたら完了」と言える具体的な状態

既に書いてくれている内容は再度聞かない。3点が揃ったら C-2 へ進む。

C-2 Issue ドラフト提示

以下のフォーマットで提示し、確認を取る:

## Issue ドラフト

**タイトル**: {簡潔な英語タイトル（50文字以内）}

**本文**:
---
## Background
{なぜ必要か}

## Requirements
{何を実現するか（箇条書き）}

## Acceptance Criteria
- [ ] {完了条件1}
- [ ] {完了条件2}
---

**ラベル**: {enhancement / tech-debt / bug から該当するもの}

このIssueを作成してよいですか？ [y/N / 修正コメント]

修正コメントがあればドラフトを更新して再提示する。

C-3 Issue 作成

承認後:

gh issue create \
  --title "{タイトル}" \
  --body "..." \
  --label "{ラベル}" \
  --repo yukkie/AgentVillage

作成後、doc/Ideas.md のリスト先頭に ❌ マークで追記する。 docs/add-issue-{番号}-to-ideas ブランチを作成してコミットし、PR を作成する。

⚠️ 注意: Ideas.md 追記の PR 本文・コミットメッセージには Closes #XX / Fixes #XX を絶対に書かない。 GitHub がマージ時に Issue を自動クローズしてしまうため。Related to #XX も不要。Issue 番号への言及は一切しないこと。

Issue番号を表示して完了。続けてそのIssueに取り組むか確認する:

Issue #{番号} を作成しました。
続けてこのIssueの実装に取り組みますか？ [y/N]

y の場合は Phase 2（ブランチ作成）へ進む。

サブコマンド: idd import <file>

引数が import で始まる場合はこのフローへ進む。続く引数はインポートするファイルパス。

目的

チャットやメモで整理した生の Markdown ファイルを読み込み、doc/Ideas.md に統合する。 GitHub Issue は作成しない — "アイデアを整理する" フェーズ専用。

フロー

[I-1] ファイル読み込み + Ideas.md の現状確認
[I-2] 整形ドラフト提示    ← 確認
[I-3] Ideas.md に書き込み

I-1 読み込み

入力ファイルと doc/Ideas.md（存在する場合）を読む。

• Ideas.md が存在しない: 新規作成モード
• Ideas.md が存在する: 追記モード（重複するアイデアはスキップ）

I-2 整形ドラフト提示

入力内容をクラスタリングして以下のカテゴリに振り分ける:

ドラフトを提示して確認を取る:

## import ドラフト

### 新規追加（{N}件）
{カテゴリごとに箇条書き}

### スキップ（重複 {M}件）
{重複と判断した理由を簡潔に}

このまま doc/Ideas.md に書き込みますか？ [y/N / 修正コメント]

修正コメントがあれば振り分けを更新して再提示する。

I-3 書き込み

承認後、doc/Ideas.md を更新する。

• 新規作成モード: ファイルを新規作成して書き込む
• 追記モード: 既存の各セクションに追記する（既存の内容は変更しない）

完了後:

{N}件のアイデアを doc/Ideas.md に追加しました。
続けて GitHub Issue を作成しますか？ [y/N]

y の場合は idd create フローへ進む。

サブコマンド: idd revise <番号>

引数の先頭語が revise の場合はこのフローへ進む。続く引数は対象 Issue の番号。

目的

Issue 作成時点から状況が変わっているケース（別 Issue の実装で AC が既に満たされた・要件がユーザーの実際の意図と乖離した・関連 Issue のコメントに調査メモが蓄積した）を検知し、Issue 本文を現状に合わせて最新化する。

このサブコマンドは Issue の整備専用。照合 → Issue 更新 →（必要なら）Ideas.md 同期までで完結し、実装フロー（Phase 2 以降）には進まない。実装に入りたい場合は revise 後に改めて /idd {番号} を実行する。

注意: 明示的に idd revise {番号} と呼ばれたときのみ起動する。通常の /idd {番号}（番号のみ）では revise ステップは実行されない。

フロー

[V-1] 照合（本文・全コメント・関連 Issue・memory・最近クローズ Issue を読む）
[V-2] 乖離レポート + revise 案提示    ← 確認（自動編集しない）
[V-3] Issue 更新 +（必要なら）Ideas.md 同期

V-1 照合

Phase 3 の「事前調査（関連の全数洗い出し）」と同じ要領で、以下を読んで現状と Issue 本文の差分を洗う（手順詳細は Phase 3 を参照、ここでは重複させない）:

• 対象 Issue の本文 + 全コメント（gh issue view {番号} --json body,comments --repo yukkie/AgentVillage）
• 本文・コメント中の #NN 言及から関連 Issue を引く
• memory/MEMORY.md と関連 memory
• 関連キーワードで最近クローズされた Issue（gh issue list --search "{キーワード} is:closed" --repo yukkie/AgentVillage）

V-2 乖離レポート + revise 案提示

照合結果を以下のフォーマットで提示する。この時点では Issue を編集しない:

## idd revise: Issue #{番号} 照合結果

### 現状と乖離している箇所
- {要件X}: {何がどう変わったか・根拠（別 Issue #NN / コメント / memory）}

### 既に解決済みの AC
- [x] {AC}: {#NN で充足済み}

### 意図と異なる要件
- {要件Y}: {乖離内容}

### revise 案（更新後の本文）
---
## Background
...
## Requirements
...
## Acceptance Criteria
- [ ] ...
---

この内容で Issue を更新しますか？ [y/N / 修正コメント]

修正コメントがあれば案を更新して再提示する。 乖離が見つからなければ「現状と一致しています。更新は不要です」と報告して終了する。

V-3 Issue 更新 +（必要なら）Ideas.md 同期

承認後、Issue 本文を更新する:

gh issue edit {番号} --body "..." --repo yukkie/AgentVillage

続けて doc/Ideas.md を確認する。当該 Issue の行があり、revise でタイトル・要約が変わった場合のみ同期する（変化がなければ何もしない）。同期する場合は master 直 push 禁止のため docs/revise-issue-{番号} ブランチを作成してコミット・PR を作成する:

git checkout -b docs/revise-issue-{番号}
git add doc/Ideas.md
git commit -m "docs: sync issue #{番号} summary in Ideas.md after revise"
git push -u origin docs/revise-issue-{番号}
gh pr create --title "docs: sync issue #{番号} in Ideas.md" --body "..." --base master

Ideas.md 同期 PR の本文・コミットには Closes #XX を書かない（自動クローズ防止）。

更新内容を表示して完了。ここで終了する（実装フローには進まない）。

プロジェクト規律ファイル: doc/project-discipline.md

idd refine が参照するプロジェクト固有の価値観・優先度方針ファイル。 リポジトリに置くことでプロジェクトと一緒に管理・バージョン管理できる。

ファイル形式

# Project Discipline

## Sprint Goal
<!-- 現在のゴール。idd refine 実行時に更新する -->
ゴール: {例: ゲームが1ラウンド最後まで回ること}

## 優先度の価値観
<!-- 相対的な優先度判断の軸。考え方が変わったときだけ更新する -->
- リファクタリング vs 新機能: {例: 新機能優先 / バランス / リファクタリング優先}
- tech-debt の姿勢: {例: 積極的に返す / 詰まったら返す / 後回し}
- 安定性 vs 速度: {例: 安定性重視 / スピード重視 / バランス}
- その他: {プロジェクト固有の判断軸があれば}

サブコマンド: idd refine

引数が refine の場合はこのフローへ進む。

目的

定期的なバックログ整理セッション。以下の2つをまとめて行う:

1. 昇格レビュー — Ideas.md の未実装アイデアを GitHub Issue に昇格できるか判断する
2. 優先度メンテ — 既存 Issue のバックログを整理し、優先度ラベルを最新化する

Issue は作成/更新の直前に必ず確認を取る。

フロー

[R-0]  project-discipline.md の確認・更新
[R-SP] Story Point 見積もり           ← 確認
[R-1]  Ideas.md 昇格候補レビュー      ← 確認
[R-2]  選択候補を Issue 化（必要に応じてヒアリング）
[R-3]  Issue バックログ優先度サジェスト ← 確認
[R-4]  優先度ラベル更新
[R-4b] Ideas.md 優先度同期・並び替え

R-0 project-discipline.md の確認・更新

doc/project-discipline.md が存在するか確認する。

存在しない場合 — 初回インタビュー:

以下をヒアリングし、ファイルを新規作成する:

project-discipline.md がまだありません。優先度サジェストのために数点確認します。

1. 今の Sprint Goal を一言で教えてください
   （例: ゲームが1ラウンド回る、デモ準備 など）

2. リファクタリングと新機能、どちらを優先しますか？
   （例: 新機能優先 / バランス / リファクタリング優先）

3. tech-debt はどう扱いますか？
   （例: 積極的に返す / 詰まったら返す / 後回し）

4. 他に判断軸があれば教えてください（スキップ可）

回答をまとめてファイル内容を提示し、承認後に doc/project-discipline.md を作成する。

存在する場合 — Sprint Goal の確認のみ:

ファイルを読み込み、Sprint Goal だけ更新が必要か確認する:

現在の Sprint Goal: {記載されているゴール}

今もこのままですか？変わっていれば教えてください。[Enter でそのまま続行]

変更があればファイルを更新してから次へ進む。

R-SP Story Point 見積もり

オープンな Issue 一覧を取得し、sp:X ラベルが付いていない Issue に SP を見積もって提示する。

SP スケール（フィボナッチ）:

ラベル形式: sp:1 / sp:2 / sp:3 / sp:5 / sp:8 / sp:13

表示フォーマット（SP未設定 Issue のみ対象）:

## Story Point 見積もり

| # | タイトル | 提案SP | 根拠 |
|---|---|---|---|
| 71 | Eliminate redundant role: str from ActorState | sp:2 | 単一クラスの変更、影響範囲は限定的 |
| 58 | Split GameEngine phases into dedicated modules | sp:8 | 複数モジュールへの分割、テスト影響大 |
| 21 | Day 2+ pre-night judgment phase | sp:5 | 新フェーズの追加、複数ファイル変更 |

変更を適用しますか？個別に修正する場合は番号=SP で指定してください。
例: "そのまま" / "58=5" / "skip"

skip の場合は R-1 へ。

承認後:

gh issue edit {番号} --add-label "sp:{値}" --repo yukkie/AgentVillage

全 Issue の処理が終わったら R-1 へ進む。

R-1 昇格候補レビュー

doc/Ideas.md を読み、❌（未実装）アイテムを列挙する。 各アイテムについて「受け入れ条件が書けそうか」で昇格準備度を判定する:

## Ideas.md 昇格候補レビュー

| # | アイデア | 判定 | 理由 |
|---|---|---|---|
| - | エージェントの感情モデル | ✅ 昇格可能 | 要件が明確 |
| - | BGM・SE の追加 | ⚠️ 要詳細化 | スコープ不明 |
| - | リプレイ機能 | ✅ 昇格可能 | 独立した機能として切り出せる |

Issue 化したいアイデアを選んでください（番号をカンマ区切り、または "skip"）:
（⚠️ のものも選択可。足りない情報はその場でヒアリングします）

skip の場合は R-3 へ。

R-2 選択候補を Issue 化

選択された各アイデアを1件ずつ処理する。

✅ 昇格可能な場合: Ideas.md の内容を元に Issue ドラフトを自動生成して提示する。

⚠️ 要詳細化の場合: idd create の C-1 と同様に、不足している情報だけヒアリングする。

• 何が不明かを明示してから質問する（例：「スコープが不明です。どの画面/フェーズが対象ですか？」）
• 3点（何を・なぜ・受け入れ条件）が揃ったら Issue ドラフトを生成する

いずれの場合もドラフトのフォーマットは idd create の C-2 と同じ（Background / Requirements / Acceptance Criteria）。 承認後に gh issue create で作成する。

R-3 Issue バックログ優先度サジェスト

オープンな Issue 一覧を取得する:

gh issue list --repo yukkie/AgentVillage --state open --json number,title,labels,body

doc/project-discipline.md の Sprint Goal・価値観と Issue 間の依存関係・工数感を踏まえて優先度をサジェストする。

また、エラーハンドリング・エッジケース・レアケースの Issue については、以下を確認する:

• 「実運用での再現が難しいか」を判断する
• 難しい場合、Issue 本文の Acceptance Criteria に ⚠️unit test mandatory が記載されているかチェックする
• 記載がなければ、優先度更新と同時に Issue 本文に追記する（gh issue edit --body）

## Issue バックログ 優先度サジェスト

Sprint Goal「{ゴール}」・価値観「{リファクタリング vs 新機能}」をもとにサジェストします。

| # | タイトル | 現在 | サジェスト | 理由 |
|---|---|---|---|---|
| 21 | Day 2+ pre-night judgment phase | （なし） | 🔴 high | Sprint Goal に直結するコア機能 |
| 38 | GameState dataclass導入 | 🟡 medium | 🟡 medium | tech-debt、後回し方針と一致 |
| 42 | エージェント感情モデル | （なし） | 🟢 low | 今の Goal では不要な拡張機能 |

変更を適用しますか？個別に修正する場合は番号と優先度を指定してください。
例: "そのまま" / "21=medium" / "skip"

優先度ラベルの種類: priority:high / priority:medium / priority:low

R-4 優先度ラベル更新

確定した変更内容を確認してから実行:

以下のラベルを更新します:
- Issue #21: （なし） → high
- Issue #42: （なし） → low

続けてよいですか？ [y/N]

承認後:

gh issue edit {番号} --add-label "priority:{値}" --remove-label "priority:{旧値}" --repo yukkie/AgentVillage

完了後にサマリーを表示する。

R-4b Ideas.md 優先度同期

優先度ラベル更新後、doc/Ideas.md の優先度表記を GitHub ラベルに合わせて同期する。

• 絵文字マッピング: priority:high → 🔴 / priority:medium → 🟡 / priority:low → 🟢
• 優先度順（🔴 → 🟡 → 🟢）に行を並び替える
• 同一優先度内の順序は変更しない

R-5 コミット & PR 作成

doc/Ideas.md や doc/project-discipline.md に変更があった場合、以下の手順でコミット・PR を作成する。

ブランチ名の形式:

docs/backlog-refinement-#{セッション番号}

• セッション番号は 1 から始め、毎回の idd refine 実行で +1 する
• 現在のセッション番号は git branch -a | grep backlog-refinement で確認する

手順:

git checkout -b "docs/backlog-refinement-#{N}"
git add doc/Ideas.md doc/project-discipline.md
git commit -m "docs: backlog refinement #{N} — {変更内容の要約}"
git push -u origin "docs/backlog-refinement-#{N}"
gh pr create --title "docs: backlog refinement #{N}" --body "..." --base master

PR 作成後に URL を表示して終了。

通常フロー

Issue選択 → ブランチ作成 → ドキュメント確認 → 設計承認 → ドキュメント更新 → 実装 → PR作成 の順に進み、フェーズが変わるたびにユーザーの確認を取る。

フェーズ概要

[1] Issue 選択
[2] ブランチ作成              ← 確認
[3] ドキュメント確認（読む）
[4] 設計検討 → スメル発見で 4.5 へ中断、なければ設計提示 → 承認後に任意で外部レビュー ← 確認
[4.5] コードスメル対話        ← 決着まで対話ループ → 4 に戻る
[5] ドキュメント更新（書く）
[6] 実装 + テスト
[7] PR 作成                   ← 確認
[8] 教訓の振り返り（任意・pull 型） ← PR 後の区切りで一度だけ。y/N

[*] スコープ拡張ゲート（横断）  ← 任意フェーズで発火。ユーザー追加指摘 / PR レビュー指摘で当初 AC 外の要求が来たとき

Phase 1 — Issue 選択

番号が指定された場合（例: /idd 42）

そのまま Phase 2 へ進む。

番号が指定されていない場合

doc/Ideas.md を読み込み、未実装 Issue の一覧を表示する。

表示フォーマット:

## 取り組む Issue を選んでください

| # | 優先度 | ラベル | タイトル | 内容 |
|---|---|---|---|---|
| 37 | 🟡 | tech-debt | `build_system_prompt` のパラメータ過多 | パラメータを整理してシンプルに |
| 21 | （なし） | enhancement | Day 2+ pre-night judgment phase | 昼開始前の判断フェーズを Day 2+ にも拡張 |
...

番号を入力してください（例: 42）:

tech-debt は表の先頭に並べる（同一優先度内でも tech-debt を上位に表示する）。

ユーザーが番号を入力するまで待つ。

注意: Ideas.md に載っている Issue が GitHub 上ですでに CLOSED になっている場合は、一覧表示後に「#XX は GitHub 上でクローズ済みです。Ideas.md から削除しますか？」と確認し、承認されたら docs/cleanup-ideas ブランチを作成して削除・コミットし、PR を作成する。

Phase 2 — ブランチ作成

ブランチ名の決め方

Issue のラベルに応じてプレフィックスを使い分ける:

形式: {prefix}issue-{番号}-{Issue タイトルを kebab-case に変換した短縮形}

例:

• Issue #37「build_system_prompt のパラメータ過多」（tech-debt）→ refactor/issue-37-build-system-prompt-params
• Issue #24「Role class refactoring」（enhancement）→ feature/issue-24-role-class-refactoring

タイトルが長い場合は 4〜5 単語に収める。

ブランチ作成手順

オープン PR チェック（必須）

ブランチ作成前に、マージされていない PR が存在するか確認する:

gh pr list --repo yukkie/AgentVillage --state open --json number,title,headRefName,baseRefName

オープン PR が1件以上ある場合は、以下を表示して警告する:

⚠️  マージされていない PR があります:

| # | タイトル | ブランチ |
|---|---|---|
| {番号} | {タイトル} | {headRefName} → {baseRefName} |
...

これらが今回の実装と関連している場合、先にマージしておかないとコンフリクトが発生する可能性があります。
続けてブランチを作成しますか？ [y/N]

N の場合は処理を中断する。y の場合は次の手順へ進む。

現在のブランチが master の場合

確認なしで以下を実行する:

git pull --rebase origin master
git checkout -b {prefix}issue-{番号}-{名前}

現在のブランチが master 以外の場合

以下を提示してユーザーに確認する:

現在のブランチ: {現在のブランチ}

作業ブランチを作成するには master ベースが必要です。
master に切り替えて pull しますか？ [y/N]

承認後:

git checkout master
git pull --rebase origin master
git checkout -b {prefix}issue-{番号}-{名前}

拒否された場合は処理を中断し、ユーザーに手動で master へ切り替えるよう案内する。

Phase 3〜6 — 実装対象による分岐

事前調査（設計 Issue・横断的変更では必須）

Issue が 設計 Issue（doc 更新・スキーマ定義） または 横断的変更（ログ/イベントフォーマット・共通データ型・複数モジュールにまたがる契約変更） の場合、Phase 3 に入る前に以下を必ず実施してから設計を組む。これを飛ばすと「見落とし → 設計やり直し」になりやすい（実例: #344 で wolf_chat の同種ハック・CLI renderer の consumer・co_announcement の二重化を初回に拾えなかった）。

1. 関連の全数洗い出し — 対象 Issue の全コメントを読む（gh issue view N --json comments）。本文・コメント中の 依存: / #NN 言及をたどって関連 Issue を引く。memory/MEMORY.md と関連 memory を確認する。同種キーワードで既存 Issue を検索する（gh issue list --search）。
2. 同種ハック/回避策の全数探索 — 回避策（プレフィックス・別イベント emit・フラグ分岐等）を1つ見つけたら、「同じ回避策が他の経路にもないか」を grep で網羅する。1箇所直して他を残すと中途半端になる。
3. producer / consumer の全列挙 — スキーマ・フォーマットを変える場合、それを emit する側（producer） と 読む側（consumer） を機械的に全部挙げる。consumer は CLI renderer・JS parser・replay・テストなど複数言語にまたがることが多い（CLI renderer の見落としに注意）。LogEvent / EventType / spectator_log.jsonl / エージェント JSON のデータ契約は doc/DataSpec.md が SSOT。EventType 一覧・可視性ルール・スキーマはまずここを参照し、変更時は doc/DataSpec.md も併せて更新する。
   • ⚠️ grep が届かない境界に注意 — consumer の中にはプロジェクト外（別リポジトリ）にあるものが存在する。とくに idd スキル定義（~/.claude/skills/idd/ 配下の SKILL.md / references/flow-*.md）はプロジェクトの doc・データ契約を参照しているが、d:\git\AgentVillage を grep しても出てこない。doc・データ契約・データスキーマを変更／新設するときは、スキル定義側に追従が必要な参照（読み物リスト・事前調査手順・ドキュメント表など）がないかを別途・明示的に確認する。 プロジェクトの変更が別リポジトリの手順書を陳腐化させても、同じ PR では担保されないため、ここで意識的に拾う（実例: #415 で doc/DataSpec.md 新設時、Issue 本文は flow-js.md のみ挙げていたが、実際は flow-python.md / SKILL.md / CLAUDE.md のドキュメント表も追従が必要だった）。
4. 後方互換の定型確認 — 過去ログ・既存データへの影響、read/write の非対称（emit は新方式・read はフォールバック等）、フォールバックの要否をユーザーに確認する。
5. 分割の選択肢提示 — 実装が大きい場合、分割の軸を明示して2〜3案を提示し、判断はユーザーに委ねる（producer/consumer 軸・言語軸など）。AI が案を勝手に1つに決めない。

未解決事項の行き先 — memory ではなく Issue

調査・設計中に見つかった 未解決の作業項目・設計判断・「後でやる」事項 は、その場で解決しないなら必ず GitHub Issue に反映する（既存 Issue に追記、なければ新規作成）。memory には書かない。

• 理由: Issue 管理の目的（追跡可能・人間も他セッションも追える・作業の単一ソース）は本スキルの前提。未解決事項を memory に入れると検索性が低く分散し、次の作業で recall されず見落とす（実例: #344 で co_announcement 統合の必要性が memory に埋もれ、初回調査で拾えなかった）。
• memory に書いてよいのは「明日この作業の続きをやる」のような作業途中のセッション状態だけ。未解決の仕様・設計・タスクは Issue へ。
• ユーザーの恒久的な好み・進め方（feedback）は従来どおり memory でよい（それは作業項目ではない）。

参照ファイルの読み込み

Issue の変更対象が src/（Python）か frontend/（JS）かを確認し、対応する参照ファイルを読んでから Phase 3 へ進む:

• Python 実装: references/flow-python.md を読む
• JS/フロントエンド実装: references/flow-js.md を読む

両方にまたがる場合は両方を読む。

Phase 7 — PR 作成

前提チェック: 以下の2つがともにユーザー承認済みであること。

1. AC 対応テスト確認表（Phase 6「AC 対応テストチェック」）
2. カバレッジ確認結果の表（Phase 6「カバレッジ突合せ」）

いずれか未提示・未承認の場合は PR 作成前に必ず提示する。

PR の内容を以下のフォーマットで提示し、確認を取る:

## PR を作成します

タイトル: {PR タイトル（50文字以内）}

本文:
---
## Summary
- {変更点1}
- {変更点2}

## Implementation notes
- {実装中に追加したリファクタリングがあれば、何を・なぜ・挙動変更の有無を記載}
- {HTML 要素変更に伴う暗黙の挙動・UA スタイル差分があれば記載}

## Test plan
- [ ] `ruff check .` パス
- [ ] `pytest` パス
- [ ] {機能固有のテスト観点}

Closes #{番号}
（複数Issueをクローズする場合は各番号にキーワードを付ける: `Closes #203, closes #205`）

🤖 Generated with [Claude Code](https://claude.com/claude-code)
---

このPRを作成してよいですか？ [y/N]

Ideas.md の更新

PR 作成前に、doc/Ideas.md の該当 Issue 行を削除してコミット・プッシュする（masterへの直接pushは禁止のため、feature ブランチ上でコミット）:

git add doc/Ideas.md
git commit -m "docs: remove issue #{番号} from Ideas.md (completed)"
git push

PR 作成

承認後:

gh pr create \
  --title "{タイトル}" \
  --body "..." \
  --base master

PR URL を表示する。

PR 作成後、PR レビュー指摘を受けたら、その指摘が当初 AC の範囲内かを確認する。当初 AC になかった要求が含まれる場合は下の「スコープ拡張ゲート（横断）」へ進む。

スコープ拡張ゲート（横断）

任意のフェーズで発火しうる割り込みゲート。Phase 4.5（コードスメル対話）と同じく、特定フェーズに属さず必要なときに起動する。

発火条件

当初 Issue の AC になかった要求が外部から入ってきたとき。トリガーは実質この2つ:

1. ユーザーの追加指摘（対話中に新しい要求・観点が足された）
2. レビュー指摘（Phase 7 後、ユーザー・第三者・CODEX 等の PR レビューで AC 外の要求が判明）

AI が実装中に自発的に「スコープが広がった」と気づくケースは想定しない（実態として起きない）。本ゲートは外部入力に対するハンドラである。これを欠くと contract テストの設計が後追いになり、既存挙動との組み合わせ境界が漏れる（実例: #417 — 「CO 発言以降に継続表示」が後から追加され、「同一 day 内の CO 前発言には表示しない」×「前 day の CO が初期状態として継続表示される」の組み合わせ境界テストが抜けた）。

手順

発火したら、まず 追加/変更したい AC の案だけ を提示する（この時点では Issue 編集も実装もしない）:

## スコープ拡張ゲート

### 追加/変更したい AC（案）
- [ ] {新 AC 1}
- [ ] {新 AC 2}

### 対処方針のサジェスト
| 観点 | 評価 |
|---|---|
| 追加 AC は独立した受け入れ条件として書けるか | {書ける / 元 AC と密結合} |
| 影響範囲（ファイル・レイヤ） | {元 Issue 内に閉じる / 別レイヤに波及} |
| 追加工数の目安 | {元 SP と同等以下 / 同等以上} |
| 元 AC との組み合わせ境界 | {疎 / 密} |

→ サジェスト: **{取り込む / 別 Issue 化 / 却下}**（理由: ...）

どうしますか？（取り込む / 別 Issue 化 / 却下 / AC 案を修正）

⚠️ 規模はユーザーが決める: AI は「大きい/小さい」を勝手に断定して取り込みに流してはならない。 上表の客観シグナルを提示し、最終判断はユーザーに委ねる。

ユーザーの選択に応じて分岐する:

• 取り込む — 下記 1→2→3 を順に行ってから、中断していたフェーズへ戻る
• 別 Issue 化 — idd create（C-2/C-3）で新 Issue を作成する。現 Issue は当初スコープで閉じ、追加分は新 Issue 側で別途実装する
• 却下 — スコープ外として扱い、当初 AC のまま進める（残す価値があれば doc/Ideas.md に追記）

「取り込む」を選んだ場合の手順（この順序を守る）:

1. AC 更新 — 上記の AC 案で Issue 本文を更新する（gh issue edit {番号} --body ... --repo yukkie/AgentVillage）
2. contract テスト設計 — 追加 AC に対応する contract テストを設計・追加する。references/flow-*.md の「Contract テストの TDD ルール」に従い、RED を確認してから実装する
3. 境界ケース列挙 — 追加 AC と既存テストの組み合わせ境界を列挙し、漏れを確認する（「新 AC が既存条件と交差する点」を洗い出す）

3 まで終えたら、中断元フェーズの「AC 対応テストチェック」へ戻り、更新後の AC で確認表を作り直す。

Phase 8 — 教訓の振り返り（任意・pull 型）

PR 作成後の区切りに到達したら、wisdom-capture スキルを起動する。

このセッションで「ユーザーが Claude の提案を否認・修正し、その後に承認へ到達した」判断があれば、それは言語化できる暗黙知の候補。wisdom-capture がそれを検出し、ルール化（スキル追記）・Issue 化・寝かせる、を y/N で提案する。発火条件・動作・不変条件（主導権はユーザー・割り込まない・寝かせるを第一選択肢に）は wisdom-capture/SKILL.md に定義されているため、ここでは重複させない。

否認がなければ発火しないのが正しい。空振りを避けようと無理に教訓を捻り出さないこと。

エラー処理