resolve-beagle

解決：仕様書の未解決項目を解消する

brainstorm-beagle で作成された仕様書を対象に、明示された未解決の質問と、自己レビューで見落とされた潜在的な問題の両方を調査し、回答を提案して仕様書を直接書き換えることで、残された不備を解消します。

最終的には、既知の未解決の質問もプレースホルダー要件もない仕様書にします。すぐに計画を開始できます。

<hard_gate> このスキルでは、コードの作成、プロジェクトのスキャフォールディング、アーキテクチャの設計、実装計画の作成は行いません。仕様書の編集のみを行います。「未解決の質問に回答する」とは、根拠を添えて WHAT／WHY の回答を提案することであり、HOW の提案ではありません。質問への回答に実装設計が必要だと判明した場合は、注記を添えて保留し、次に進んでください。 </hard_gate>

ゲート（次のステップに進む前に通過すること）

アサーションだけでは手順を省略できないよう、客観的な通過条件を設けています。

1. 仕様書の特定 — 対象ファイルのパスが判明し、Read が成功していること（または、docs/specs/ 内の最近の候補を 3〜5 件提示した後に、ユーザーが有効なパスを提示していること）。
2. 不備リストの提示 — 明示された未解決の質問の箇条書きすべてと、対象範囲に含める各潜在的な不備を、1 回のメッセージで提示すること。ユーザーがリストを調整（追加／削除／保留）するか、そのリストで進めるよう明示するまでは、調査を開始しないでください。
3. 不備ごとの調査成果物 — 不備 G の提案を提示する前に、G に関する構造化されたメモを作成すること。推奨する回答、却下した代替案 1〜2 件とその理由、根拠（ファイルと行番号、URL、または仕様書内の引用）を含めます。この成果物なしに提案してはいけません。
4. 提案キューは 1 件ずつ — 現在の不備について明確な結論（承認、文言の修正と反映、次の対応を伴う却下、または理由を添えた保留）が出るまで、次の不備の提案に進まないでください。
5. 書き換え内容の整合性確認 — 編集後、仕様書全体を 1 回読み、セクション間の矛盾を解消します。その後、../brainstorm-beagle/references/spec-reviewer.md の自己レビューチェックリストを実行し、ユーザーが後日対応を選ばない限り、見つかった不備をその場で修正します。
6. コミット — §「コミット」にある質問にユーザーが「はい」と答えない限り、git commit は行いません。

ワークフロー

1. 仕様書を特定する — ユーザーが明示したパスを使うか、docs/specs/ 内で最も新しいファイルを選びます。
2. 不備を抽出する — 「未解決の質問」を確認し、潜在的な問題（プレースホルダー、曖昧な要件、根拠の欠如、矛盾）も監査します。
3. 不備リストを提示する — 解消する予定のすべての項目を 1 つの要約にまとめ、調査開始前にユーザーが追加・削除できるようにします。
4. 調査を割り当てる — 不備ごとに 1 つのタスクを設定し、サブエージェントが使える場合は並列で、使えない場合はインラインで順次実行します。
5. 回答を提案する — 推奨案、代替案、根拠を添えて、一度に 1 件ずつ提案します。
6. 仕様書を直接書き換える — 解決済みの項目を適切なセクションに移します。何も黙って削除してはいけません。
7. 自己レビューを行う — brainstorm-beagle と同じチェックリストを使用します（../brainstorm-beagle/references/spec-reviewer.md を参照）。
8. コミットするか確認する — 編集内容をコミットするかユーザーに尋ねます。確認なしにコミットしてはいけません。

Locate spec → Extract gaps → Show list ──→ User adds/removes
                                          → Dispatch research (parallel if possible)
                                          → Propose answers (one at a time)
                                                → User decision → next
                                          → Rewrite spec in place
                                          → Self-review (fix inline)
                                          → Ask about committing

仕様書の特定

ユーザーがパスを提示している場合は、そのパスを使います。

提示されていない場合は、docs/specs/ 内で更新日時が新しいファイルを 3〜5 件一覧表示し、次のように尋ねます。「<most recent> に取り組みますか、それとも別のファイルにしますか？」ディレクトリツリー全体を走査してはいけません。brainstorm-beagle の規約では、仕様書はディレクトリ直下に置かれます。

仕様書ディレクトリが存在しない場合は、ユーザーにパスを尋ねてください。

ギャップの抽出

ギャップには、次の2つのカテゴリがあります。

明示的なギャップ — 仕様の Open Questions 見出しの下にある各項目が、1つの調査タスクです。

潜在的なギャップ — ブレインストーミングの自己レビューをすり抜けた問題です。仕様を確認し、次の点を探してください。

問題	具体例
プレースホルダー	TBD、TODO、「未定」、内容の代わりに使われた省略記号
曖昧な要件	「高速」「シンプル」「良好」「ユーザーフレンドリー」「直感的」など、検証の基準がないもの
根拠の欠如	「制約」または「スコープ外」の項目に「なぜ」がないもの
矛盾	要件が別の要件、制約、または「スコープ外」の項目と矛盾しているもの
テスト不能な成功条件	要件が満たされたことを検証するための、観測可能な方法がないもの
実装の詳細への踏み込み	「何を」ではなく「どのように」を規定している要件
未使用のインターフェース	必須要件が新たに外部公開されるインターフェース（API サーフェス、コマンド、エンドポイント、エクスポートされるコントラクト）を導入しているが、仕様内のほかの箇所で利用されていないもの
未検討の組み合わせ	既存の仕組みが同じデータパイプラインの上流または下流にあり、機能が依存するデータを変換（切り詰め、フィルター、バッファリング、並べ替え、重複排除）するものの、その機能との組み合わせが検討されていないもの

潜在的なギャップを明示的なギャップと同等に扱う理由は、仕様に「高速」や「優れた UX」と書かれていれば、誰も問題として指摘しなかったとしても、回答済みにはならないからです。計画を立てるときにも、同じ曖昧な表現が障害になります。ここで解消してください。

調査を割り当てる前に、統合した一覧を1つのメッセージでユーザーに提示し、「解消しようとしている項目は次のとおりです」と伝え、項目の追加、削除、延期を可能にしてください。1項目ずつ許可を求めないでください。これは提案の段階です。

調査の割り当て

各ギャップには、調査タスクを1つだけ割り当てます。まず各タスクを分類してください。分類によって、調査に必要なツールが決まります。

タスクの種類	例	ツール
コードベースのパターン	「既存の --start-at パターンはどのように機能しますか？」「SKILL_MAP はどこで定義されていますか？」	コードベースを検索する（grep/glob/read）
外部仕様／API	「エージェントの SDK は、サブエージェントの起動にどのような機能を公開していますか？」「Codex にはフックがありますか？」	ウェブ検索とページ取得（ウェブアクセスが利用可能な場合）
設計上のトレードオフ	「統合レポートの形式はどうすべきですか？」「重複排除はどのように行うべきですか？」	仕様にすでに記載されている推論と類似の参考事例
スコープ／ポリシー	「設定ファイルやドキュメントファイルは、スタックに振り分けるべきですか、それともフォールバックさせるべきですか？」	仕様自体の中核的価値と制約に基づく推論

サブエージェントを使う場合（推奨）

エージェントがサブエージェントに対応している場合は、各調査タスクを独立したサブエージェントに割り当ててください。すべて同じターンで割り当て、並列に実行します。 各サブエージェントには独自のコンテキストウィンドウが割り当てられます。ギャップの調査には仕様やコードベースなど、大量の関連コンテキストが必要になることが多いため、1つの会話に詰め込まずに済みます。

タスクの種類ごとのプロンプトテンプレートについては、references/subagent-prompts.md を参照してください。

調査結果は、推奨する回答、採用しない理由を含む代替案1～2件、具体的な根拠（ファイルと行番号の引用、URL、または仕様内の既存セクションへの参照）の形式にします。各調査結果は約300語以内にまとめてください。必要なのは議論の記録ではなく、判断です。

サブエージェントを使わない場合

サブエージェントツールが利用できない場合は、自分で1つずつ調査してください。最も低コストなものから順に、コードベースに関する質問、外部に関する質問、トレードオフ、スコープ／ポリシーの順に進めます。それぞれについて、同じ形式の提案を作成してください。時間はかかりますが、ギャップを未解決のまま残すことはありません。

回答案の提示

回答案は一度に1つずつ提示します。それぞれについて、次の内容を示します。

• ギャップ — 1行で言い換えます
• 推奨する回答 — 最善と考える案と、その理由を示します
• 代替案 — 有力な選択肢を1～2個挙げ、採用しない理由を説明します
• 根拠 — ファイル名と行番号の引用、URL、または仕様内ですでに決定済みの事項への参照を示します

ユーザーは、案を承認、修正、または却下できます。議論を続けたい場合はその話題を続け、決定したら次に進みます。

順序が重要です。 おおむね次の順序で解決します。

1. まず、コードベースの実態に関するギャップ（設計上のトレードオフを判断する材料になる場合があります）
2. 次に、ポリシー／スコープに関するギャップ（以降のすべてに影響します）
3. 最後に、形式／提示方法に関するギャップ（前述の内容に依存します）

ユーザーしか提供できない情報（予算、ステークホルダーの希望、明示されていない制約）がないと解決できないギャップについては、推測せず、直接質問してください。誤った案を提示して後から覆すより、そのほうが効率的です。

仕様の書き換え

決定が固まったら、該当する箇所に反映します。

ギャップの種類	解決後の移行先
アーキテクチャまたはポリシー上の決定	Key Decisions の下に、検討した代替案とともに新しい項目を追加
具体的な動作	Requirements の下に、新しい項目を追加（must／should／out-of-scope を割り当て）
厳格な制限	Constraints の下に、理由とともに新しい項目を追加
調査中に見つかった外部参照先	Reference Points の下に、新しい項目を追加
曖昧な要件を置き換えた場合	既存の要件をその場で書き換え、重複させない
意図的に保留した場合	deferred: <reason> を付記して Open Questions に残す

重要なルールが2つあります。

• Open Questions の項目を黙って削除しないでください。 解決するか、理由とともに移行するか、理由を明記して保留にしてください。履歴を残さずに質問を削除すると、セッションをまたいだ仕様の後退につながります。
• 変更箇所だけでなく、仕様全体を書き直してください。 変更の影響は他の箇所にも及びます。新しい Key Decision が既存の Requirement と矛盾したり、解決済みの Open Question によって Constraint が無効になったりすることがあります。編集後は仕様を最初から最後まで読み、整合性を取ってください。

セルフレビュー

../brainstorm-beagle/references/spec-reviewer.md にあるチェック項目を実行します。

• プレースホルダーがない
• 矛盾がない
• 実装の詳細が漏れ込んでいない
• すべての要件がテスト可能である
• Constraint と Out-of-Scope 項目に理由がある
• 新たに外部に公開するサーフェス（API サーフェス、コマンド、エンドポイント、エクスポートされたコントラクト）には、名前が明示された利用者がいる。利用者の名前を記載するか、Future Considerations に移す
• 機能のデータを変換する既存の上流／下流パイプラインの仕組みがある場合、調査せずに放置せず、needs-spike-before-planning タグを付けた Key Decision として記録する

ユーザーに返す前に、見つかった問題はその場で修正します。書き換え中に新たなギャップが見つかった場合（ときどきあります）は、「new gaps surfaced」リストに追加し、今解決するか、後の作業に残すかをユーザーに尋ねます。

コミット

書き換え後、変更内容を要約して次のように尋ねます。

「仕様を更新しました。明示的な質問 N 件と潜在的なギャップ M 件を解決しました。これを docs: resolve open questions in <topic> spec としてコミットしますか？」

承認された場合はコミットします。承認されない場合は、作業ツリーをそのまま残します。ユーザーが差分を確認したり、ほかの変更とまとめたりする可能性があるため、許可なくコミットしないでください。

重要な原則

• 最後まで詰めます。 目標は、計画を妨げる未回答の項目がない仕様です。半端に解決するより、明確に先送りするほうがよいです。
• ギャップごとに調査タスクを1つ設定します。 タスクを曖昧にまとめないでください。提案のレビューが難しくなり、根拠をたどりにくくなります。
• 意見より根拠を重視します。 提案にはすべて、ファイル、URL、既存の仕様上の決定などを根拠として示します。「そう思う」だけでは不十分です。
• あくまで「何を」であり、「どのように」ではありません。 回答は実装設計ではなく、仕様上の決定として反映します。実装について考える必要がある回答は先送りしてください。
• 正直に先送りします。 今すぐ回答するにはコストがかかりすぎる質問は、理由を1行添えて未解決の質問として残します。既知のギャップを取り繕うより、認めるほうがよいです。
• 可能であれば並列化します。 サブエージェントは分離された環境で動作するため、積極的に並行して進めてください。順次調査は既定の方法ではなく、代替手段です。
• 不必要に作業を中断しません。 ギャップの一覧は一度だけ提示し、その後は人の判断が必要な決定についてのみユーザーに確認します。