clarify

ユーザー入力

$ARGUMENTS

空でない場合は、作業を進める前にユーザー入力を必ず考慮してください。

概要

目的：現在の機能仕様における曖昧な点や、意思決定が不足している箇所を検出して解消し、明確化した内容を仕様ファイルに直接記録します。

注：この明確化ワークフローは、bb-plan スキルを実行する前に開始し、完了している必要があります。ユーザーが明確化を省略すると明示した場合（例：探索的なスパイク）は、先に進んでもかまいませんが、後続作業での手戻りリスクが高まることを警告してください。

実行手順：

1. 現在の機能ディレクトリを特定し、機能仕様が存在することを確認します。最低限のペイロードフィールドを解析します。

   • FEATURE_DIR
   • FEATURE_SPEC
   • （必要に応じて、後続の連携フローに備えて IMPL_PLAN、TASKS も取得します。）
   • 機能ディレクトリまたは仕様が見つからない場合は中止し、先に bb-specify スキルを実行するか、機能ブランチの環境を確認するようユーザーに指示します。
   • 「I'm Groot」のように引数にシングルクォートが含まれる場合は、エスケープ構文を使用します。例：'I'''m Groot'（可能であればダブルクォートを使用します：「I'm Groot」）。

2. 現在の仕様ファイルを読み込みます。以下の分類に沿って、曖昧さと網羅性を体系的に確認します。各カテゴリのステータスを「明確」「一部明確」「不足」のいずれかにします。優先順位付けに使用するカバレッジマップを内部で作成します（質問をしない場合を除き、生のマップは出力しないでください）。

   機能範囲と動作：

   • 中核となるユーザーの目標と成功基準
   • 明示的な対象外の宣言
   • ユーザーの役割／ペルソナの区別

   ドメインとデータモデル：

   • エンティティ、属性、関係
   • 識別と一意性のルール
   • ライフサイクル／状態遷移
   • データ量／規模に関する前提

   インタラクションと UX フロー：

   • 重要なユーザージャーニー／シーケンス
   • エラー／空／読み込み状態
   • アクセシビリティまたはローカライズに関する注記

   非機能品質属性：

   • パフォーマンス（レイテンシ、スループットの目標）
   • スケーラビリティ（水平／垂直、上限）
   • 信頼性と可用性（稼働時間、復旧への期待）
   • オブザーバビリティ（ログ、メトリクス、トレースのシグナル）
   • セキュリティとプライバシー（認証／認可、データ保護、脅威に関する前提）
   • コンプライアンス／規制上の制約（該当する場合）

   統合と外部依存関係：

   • 外部サービス／API と障害モード
   • データのインポート／エクスポート形式
   • プロトコル／バージョンに関する前提

   エッジケースと障害処理：

   • 否定的なシナリオ
   • レート制限／スロットリング
   • 競合の解決（例：同時編集）

   制約とトレードオフ：

   • 技術的制約（言語、ストレージ、ホスティング）
   • 明示的なトレードオフ、または却下した代替案

   用語と一貫性：

   • 標準用語集の用語
   • 避けるべき同義語／非推奨の用語

   完了の指標：

   • 受け入れ基準のテスト可能性
   • 測定可能な完了定義の指標

   その他／プレースホルダー：

   • TODO マーカー／未解決の決定事項
   • 定量化されていない曖昧な形容詞（「堅牢」「直感的」など）

   「一部明確」または「不足」のカテゴリごとに、以下に該当しない限り、質問候補を追加します。

   • 明確化しても実装や検証の方針が実質的に変わらない
   • 情報を計画フェーズまで保留するほうが適切である（内部で注記してください）

3. 優先順位を付けた確認質問の候補キューを（内部で）作成します（最大5件）。一度にすべて出力してはいけません。以下の制約を適用してください。

   • セッション全体での質問数は最大10件です。
   • 各質問は、次のいずれかで回答できるものにしてください。
     • 短い複数選択（相互に重複しない選択肢を2～5個）
     • 1語または短いフレーズでの回答（「5語以内で回答」と明示）
   • アーキテクチャ、データモデリング、タスク分解、テスト設計、UX の動作、運用準備、またはコンプライアンス検証に実質的な影響を与える質問のみを含めてください。
   • カテゴリーの網羅性のバランスを保ってください。影響の大きい未解決カテゴリーから優先して確認し、セキュリティ体制などの影響が大きい領域が未解決のまま、影響の小さい質問を2件尋ねることは避けてください。
   • すでに回答済みの内容、些細な文体上の好み、または正確性を損なわない計画レベルの実行詳細は除外してください。
   • 後工程での手戻りリスクを下げる、または受け入れテストの不一致を防ぐ質問を優先してください。
   • 未解決のカテゴリーが5つを超える場合は、（影響度 × 不確実性）の基準で上位5つを選んでください。

4. 順次質問する対話ループ：

   • 質問は必ず一度に1件だけ提示してください。

   • 複数選択式の質問の場合：

     • すべての選択肢を分析し、次の観点から最適な選択肢を判断してください。
       • プロジェクトの種類に応じたベストプラクティス
       • 類似の実装で一般的なパターン
       • リスクの低減（セキュリティ、パフォーマンス、保守性）
       • 仕様に明示されたプロジェクトの目標や制約との整合性
     • 推奨する選択肢を先頭に目立つように示し、これが最適である理由を1～2文で説明してください。
     • 次の形式を使用してください：**推奨:** 選択肢 [X] - <理由>
     • 続けて、すべての選択肢を Markdown テーブルで表示してください。

     選択肢	説明
     A	<選択肢 A の説明>
     B	<選択肢 B の説明>
     C	<選択肢 C の説明>（必要に応じてD/Eを追加し、最大5個まで）
     その他	別の短い回答を入力してください（5語以内）（自由回答が適切な場合のみ含める）

     • テーブルの後に、次の文を追加してください。選択肢の文字（例：「A」）、推奨案への同意を示す「yes」または「recommended」、または別の短い回答で返信できます。

   • 短答式（意味のある明確な選択肢がない場合）の場合：

     • ベストプラクティスと文脈に基づき、推奨する回答を提示してください。
     • 次の形式を使用してください：**提案:** <推奨する回答> - <簡潔な理由>
     • 続けて、次の文を出力してください。回答形式：5語以内の短い回答。「yes」または「suggested」で提案に同意するか、独自の回答を入力してください。

   • ユーザーが回答した後：

     • ユーザーが「yes」、「recommended」、または「suggested」と返信した場合は、直前に提示した推奨案または提案を回答として使用してください。
     • それ以外の場合は、回答が選択肢のいずれかに該当すること、または5語以内であることを確認してください。
     • 曖昧な場合は、すばやく確認質問をしてください（質問数は同じ質問として数え、次へ進まないでください）。
     • 回答が確定したら、作業メモリに記録し（まだディスクには書き込みません）、次のキュー内の質問に進んでください。

   • 次の場合は、以降の質問を終了してください。

     • 重要な曖昧さがすべて早期に解消され、残りのキュー内の項目が不要になった場合
     • ユーザーが終了の意思を示した場合（「done」、「good」、「no more」）
     • 質問が5件に達した場合

   • 以降のキュー内の質問を事前に明かしてはいけません。

   • 開始時点で有効な質問がない場合は、重要な曖昧さがないことを直ちに報告してください。

5. 承認された各回答の後に統合する（逐次更新方式）：

   • 仕様のインメモリ表現（開始時に一度だけ読み込み）と生のファイル内容を保持します。
   • このセッションで最初に回答を統合する際：
     • ## Clarifications セクションが存在することを確認します。存在しない場合は、仕様テンプレートに従い、最上位のコンテキスト／概要セクションの直後に作成します。
     • その下に、今日の日付を使った ### Session YYYY-MM-DD サブ見出しを作成します（存在しない場合）。
   • 承認後すぐに、次の箇条書きを追加します：- Q: <question> -> A: <final answer>.
   • 続いて、明確化内容を最も適切なセクションに直ちに反映します：
     • 機能上の曖昧さ → 機能要件の箇条書きを更新または追加します。
     • ユーザーとのやり取り／アクターの区別 → 明確化された役割、制約、シナリオをユーザーストーリーまたはアクターのサブセクション（存在する場合）で更新します。
     • データ構造／エンティティ → 順序を維持しながら、データモデルにフィールド、型、関係を追加し、追加した制約を簡潔に記します。
     • 非機能制約 → 非機能要件／品質属性のセクションに測定可能な基準を追加または変更します（曖昧な形容詞を指標または明示的な目標値に置き換えます）。
     • エッジケース／否定的なフロー → エッジケース／エラー処理の下に箇条書きを追加します（テンプレートにプレースホルダーがある場合は、そのサブセクションを作成します）。
     • 用語の不一致 → 仕様全体で用語を統一します。元の用語を残す必要がある場合に限り、(formerly referred to as "X") を一度追加します。
   • 明確化によって以前の曖昧な記述が無効になる場合は、重複させず、その記述を置き換えます。矛盾する古い記述を残さないでください。
   • コンテキスト喪失のリスクを最小限にするため、統合のたびに仕様ファイルを保存します（アトミックな上書き）。
   • 書式を維持します。無関係なセクションを並べ替えず、見出し階層も変更しないでください。
   • 追加する明確化は、物語的な脱線を避け、簡潔で検証可能なものにします。

6. 検証（各書き込み後および最後の確認時に実施）：

   • Clarifications セッションには、承認された回答ごとに箇条書きがちょうど1つずつ含まれていること（重複なし）。
   • 質問数（承認済み）は5件以下であること。
   • 更新したセクションに、今回の回答で解消するはずだった曖昧なプレースホルダーが残っていないこと。
   • 以前の記述に矛盾が残っていないこと（無効になった選択肢が削除されているか確認）。
   • Markdown の構造が有効であること。追加が許可される見出しは ## Clarifications と ### Session YYYY-MM-DD のみです。
   • 用語の一貫性：更新したすべてのセクションで同じ標準用語を使用していること。

7. 更新した仕様を FEATURE_SPEC に書き戻します。

8. 完了を報告します（質問のやり取りが終了した後、または早期終了時）：

   • 質問した件数と回答済み件数。
   • 更新した仕様のパス。
   • 変更したセクション（名前を列挙）。
   • 各分類カテゴリの Status を示す網羅性サマリーテーブル。Resolved：以前は Partial／Missing で、対応済み。Deferred：質問の上限を超過、または計画策定に適切。Clear：すでに十分明確。Outstanding：影響は小さいものの、依然 Partial／Missing。
   • Outstanding または Deferred が残っている場合は、bb-plan スキルに進むか、計画後に bb-clarify スキルを再実行するかを推奨します。
   • 次のステップを提案します。

動作ルール：

• 意味のある曖昧さが見つからない場合（または、想定される質問がすべて影響の小さいものである場合）は、「正式な確認が必要な重大な曖昧さは検出されませんでした。」と回答し、次のステップへの移行を提案します。
• 仕様ファイルが見つからない場合は、まず bb-specify スキルを実行するようユーザーに指示してください（ここでは新しい仕様を作成しないでください）。
• 質問の合計数は5つを超えないようにしてください（1つの質問に対する確認のやり直しは、新しい質問として数えません）。
• 機能の明確化が妨げられない限り、技術スタックに関する推測的な質問は避けてください。
• ユーザーが早期終了の意思を示した場合（「stop」「done」「proceed」）、それに従ってください。
• 網羅性が確保されて質問をしなかった場合は、簡潔な網羅状況の要約（すべてのカテゴリが Clear）を出力してから、次のステップへの移行を提案してください。
• 質問数の上限に達し、重大な影響のあるカテゴリが未解決のまま残っている場合は、その理由とともに「保留事項」の下に明示してください。

優先順位付けのコンテキスト：{ARGS}