spec-kit-clarify

焦点を絞った順次質問を通じて、機能仕様の曖昧さを解消します。

入力：変更名を指定できます。省略された場合は、コンテキストから推測するか、質問します。 ユーザーがほかに追加した内容は、質問の優先順位を決めるためのコンテキストとして扱います。

これを spec-kit-plan の前に実行してください。 ユーザーが明示的にスキップする場合（たとえば探索的なスパイクなど）は進めてかまいませんが、後続工程で手戻りが増えるリスクがあることを警告してください。

手順

1. 変更を選択する

   specs/changes/ の下にディレクトリが1つしかない場合は、自動で選択します。それ以外の場合は質問します。

2. specs/changes/<name>/spec.md を読み込む

   存在しない場合は、まず spec-kit-specify スキルを使うようユーザーに促します。この場で仕様を作成してはいけません。 また、回答が従うべき制約を確認するため、FRAMEWORK.md（存在する場合は FRAMEWORK.local.md も）を読みます。

3. 曖昧さを確認する

   以下の各カテゴリを、優先度順に「明確」「部分的」「不足」のいずれかに分類します。

   • 機能の範囲 — 目標、対象外の宣言、不明確な境界や動作、役割
   • ドメインとデータ — エンティティ、識別性と一意性、状態と遷移、ボリューム
   • UX フロー — ユーザージャーニーの不足、変更対象の画面における失敗、待機、空、再表示、同時利用時の状態、または入力を受け付ける画面における悪意ある入力の状態が未決定
   • 非機能要件 — 性能、規模、信頼性、可観測性、セキュリティ、プライバシー、コンプライアンスの指定不足
   • 統合 — 外部依存関係と、その障害時の挙動
   • 用語 — ドメイン用語の曖昧さや不整合
   • テスト可能性 — 曖昧な形容詞（「堅牢」「直感的」など）、またはテストで判断できない受け入れ条件
   • プレースホルダー — TODO や未決定事項

   「部分的」または「不足」のカテゴリはすべて質問候補です。ただし、その回答によって実装や検証方法が変わらない場合、または実装方法、技術スタックの比較、タスク分解に関する内容は除きます。これらはここではなく計画の対象です。 仕様の ## Open Questions に記載された項目はすべて質問するか、要約で質問しなかった理由を説明します。 候補は影響度と不確実性の積が大きい順に並べます。たとえば、影響度の高い領域（セキュリティ方針など）は、影響度の低い質問2つより先に扱います。

4. 質問する前に、前提を確認する

   質問は、その前提を確定した事実としてユーザーに伝えます。ユーザーは、本来聞くべき質問ではなく、実際に聞かれた質問に答えるためです。 質問がシステムの現在の動作（存在する設定、読み取られるフィールド、適用されるルールなど）を前提とする場合は、記憶に頼らず、質問する前に対象のコードを確認してください。

5. 一度に1つずつ質問する

   質問候補を事前に開示してはいけません。 回答がアーキテクチャ、データモデリング、タスク分解、テスト、UX、運用、コンプライアンスに実質的な影響を与える場合に限り質問します。

   各質問の形式：

   • **Question:** で始まり、単独でも意味が通る疑問文を ? で終えます。 トピックラベル、見出し、要件 ID を質問として使ってはいけません。 要件 ID は ? の後ろに括弧付きで追加できます。例：**Question:** <疑問文>? (FR-03)
   • その後に、受け入れ条件やリリースにとって重要な理由を、平易な一文で説明します。 日常的な言葉を使い、Spec Kit を知らない読者でも質問だけで回答できるようにします。
   • 相互に排他的な選択肢を2〜5個提示するか、5語以内の短い回答を求めます。
   • 推奨する選択肢（または回答案）を示し、その理由を1〜2文で説明します。プロジェクトの種類に応じたベストプラクティス、リスクの低減、仕様に記載された目標や制約を考慮します。

   回答を選択肢で表せる場合は、インストールされている場所で ask-question スキルを使い、推奨する選択肢を最初に提示します。それ以外の場合は、選択肢を表にまとめ、選択肢の文字、「はい」（推奨案への同意）、またはユーザー自身の短い回答を受け付けます。 回答が曖昧な場合は、次に進む前に、同じ質問について簡潔な追加質問をします。 無人で実行する場合（FRAMEWORK.md § Unattended runs）、回答する人はいません。推奨される選択肢を採用し、その理由とともに ## Assumptions に記録してください。人による判断がどうしても必要な事項は、実行時のエスカレーション経路に送ってください。

6. 次の質問をする前に、回答を記録する

   回答を受け入れるたびに、spec.md を更新して保存します。

   • ## Clarifications（ない場合は冒頭のセクションの後に作成）に、今日の日付を使った ### Session YYYY-MM-DD サブセクションを設け、- Q: <question> → A: <answer> を追記します。
   • 回答を該当するセクションに反映します。要件とそのシナリオ、ユーザーストーリー、主要なエンティティ、成功基準（曖昧な形容詞を測定可能な目標にする）、エッジケース、または用語（用語を全体で統一し、必要に応じて (formerly "X") を一度記載）です。 新しい要件には、次に未使用の FR-nn を割り当てます。既存の識別子の番号は維持します。
   • 回答によって不要になった記述は、横に追加するのではなく置き換えます。矛盾が残らないようにしてください。
   • 回答で解決した [NEEDS CLARIFICATION] マーカーを削除します。
   • 変更は最小限かつテスト可能なものにし、無関係なセクションと見出し階層はそのまま維持します。

7. 重要な曖昧さが解消されたら終了する

   質問数に上限はありません。 重要な曖昧さがすべて解消されたとき、またはユーザーが終了を伝えたとき（「done」「proceed」）に停止します。 未解決の事項があれば、仕様書で明示してください。

8. 仕様書の品質チェックリストを再検証する

   specs/changes/<name>/checklists/requirements.md が存在する場合は、更新した仕様書に照らして各チェック項目を再評価します。 状態が変わった項目のマーカーだけを切り替え、ファイルのほかの内容は変更しないでください。 今回合格した項目、未達に戻った項目、未達のままの項目を記載します。

出力

質問が終了した後、次の内容を出力します。

• 質問した数と回答済みの数、および質問が影響した spec.md のセクション。
• チェックリストを再検証した場合は、再検証前後の件数（例：「12/16 → 15/16 が合格」）と、状態が変わった項目または未達のままの項目。
• カバレッジ表：各カテゴリの状態（Resolved、Deferred（計画フェーズに属する、またはユーザーが停止した）、Clear、Outstanding（部分的に未解決だが影響が小さい））。
• 次のステップ：「spec-kit-plan スキルを使用して、技術実装計画を作成してください。」 Outstanding または Deferred がある場合は、計画に進むか、追加で明確化するかを伝えます。

ガードレール

• 重要な曖昧さが見つからない場合は、「正式な確認が必要な重大な曖昧さは検出されませんでした。」と述べ、カバレッジ表と spec-kit-plan スキルの提案を記載します。
• 回答のたびに必ず保存します。更新をまとめて行ってはいけません。
• 明確化の過程で、仕様書に実装の詳細を追加してはいけません。
• 技術スタックの不在によって機能面の明確化が妨げられる場合を除き、技術スタックについて質問してはいけません。