spec-loop-clarify-task

ユーザーとの重要な確認事項には、このスキルを使用してください。 重要な未決事項について、話し合い、分析し、選択肢を比較し、ストレステストを行い、解決します。重要な Spec Loop の確認を、別のワークフロー内の構造化されていないサイドディスカッションとして実施しないでください。作業項目は任意です。タスクファイル、ADR、または呼び出し元のワークフローが存在しない場合は、チャットのみで確認を行います。

ADR 作業では、異なる回答によって ADR の決定またはその正当化が大きく変わる可能性がある場合、基準、代替案、決定境界の確認にこのスキルを使用してください。

重要な未決事項とは、回答によってユーザーの意図する結論、範囲、動作、ポリシー、概念モデル、概念的な契約境界、制約、経路、受け入れロジック、検証に関する期待、設計、テスト仕様、または ADR の決定やその正当化が大きく変わる可能性のある、未解決の質問、選択肢、基準、トレードオフ、有力な選択肢、境界のことです。

呼び出し元のワークフローで必須とされる決定事項のスクリーニングを除き、現在の話し合いや作業項目に重要な未決事項が明らかに含まれていない場合は、このスキルを使用しないでください。

このスキルは、質問することだけを目的としたものではありません。既存の根拠で判断できることを解決し、該当する場合は最終決定を管理対象の成果物に記録し、ユーザーの入力が引き続き必要な場合にのみユーザーに質問してください。

Spec Loop のタスク作成、タスクの更新、設計の更新、ADR 作業中の確認には、汎用的な質問攻めの手法や自由形式の話し合いよりも、このスキルを優先してください。

解決範囲

このスキルでは、既存の根拠を確認し、残る選択肢についてユーザーと話し合い、最終回答を記録することで決定事項を解決します。ADR の作成、タスクの作成、長期的な作業経路の選択は行いません。

ADR 作業、実装作業、調査、スパイク、プロトタイプ、カタログ、または実証作業が必要なため、根拠の確認とユーザーとの話し合いだけでは決定事項を解決できない場合は、ブロッカーを明示して呼び出し元のワークフローに制御を戻してください。ADR 作業に進むか、タスクまたはサブタスクを作成・更新するか、根拠が整うまで一時停止するかは、呼び出し元のワークフローが決定します。

呼び出し元のワークフローがない場合は、ブロッカーを明示して停止し、どのワークフローまたは成果物で扱うべきかをユーザーに尋ねてください。未解決の結果に依存するワークフローの手順を続けないでください。

フェーズと引き継ぎ

呼び出し元のワークフローが存在する場合、確認はそのワークフローのフェーズ内で行います。

• 計画中の確認は PLAN で続けます。
• ADR 作業中の確認は ADR 作業内で続けます。
• 実装時の確認は spec-loop-implementation-flow/SKILL.md に従います。

呼び出し元のワークフローがない場合、確認はチャット内で行います。結果をどこに記録するかをユーザーが明示しない限り、タスクファイル、ADR、用語集、その他の永続的な成果物を作成または編集しないでください。

PLAN または ADR 作業中は、必要に応じて管理対象の成果物をその場で改訂してください。実行可能な変更は許可されません。

このスキルの終了時：

• 呼び出し元のワークフローが存在する場合は、制御をそのワークフローに戻します。
• それ以外の場合は、解決済みのチャット内容と、残る未解決の質問を明確に示して終了します。

ワークフロー固有の戻り先：

• タスクの計画は spec-loop-plan-task/SKILL.md に戻ります。
• 作業の分割は spec-loop-plan-work-breakdown/SKILL.md に戻ります。
• ADR 作業中の確認は spec-loop-write-adr/SKILL.md に戻ります。
• 実行承認の準備に関する確認は spec-loop-prepare-execution-approval/SKILL.md に戻ります。
• 実装時の確認は spec-loop-implementation-flow/SKILL.md に戻ります。

必須の意思決定スクリーニング

別のワークフローで、コンテンツの作成または改訂前にこのスキルを適用するよう指示された場合、以下の意思決定ツリーと許可されたスクリーニング結果を使って、そのコンテンツに影響する重要な意思決定ポイントをそれぞれスクリーニングしてください。直感的に「質問は不要」と判断して、これを置き換えてはいけません。

重要な意思決定ポイントとは、アシスタントが判断、暗示、または最終コンテンツとして記述する必要があり、別の回答であれば、このスキルにおける重要な未決定事項となり得る選択肢を指します。

依存する最終コンテンツを作成する前に、重要な意思決定ポイントをすべて、許可されたスクリーニング結果のいずれか1つに分類する必要があります。

必須の意思決定スクリーニングで行うのは、重要な意思決定ポイントをそれぞれ分類することです。すべてについて質問することではありません。pending User answer as a clarification question の結果になった場合に限り、確認質問が必要です。

意思決定ツリー

1. 確認が必要かどうかを判断する

重要な未決定事項が残っていない場合：

• このスキルを呼び出したワークフローがある場合は、速やかに制御をそのワークフローに戻します。
• そうでない場合は、チャットのみでの確認を速やかに終了します。
• このスキルのために、確認事項のまとめや永続状態の記録を開始してはいけません。

このスキルを必須の意思決定スクリーニングに使用している場合は、スクリーニング対象のコンテンツに関する重要な意思決定ポイントがすべて、確定的な根拠または外部への確認によって解決済みと分類された後に限り、このステップで戻ってください。

2. 単純なケースにはその場で回答する

そのポイントが明らかな誤字の修正、些細な一語の曖昧さの解消、または単純な事実確認であり、回答によって範囲、動作、ポリシー、境界、受け入れ条件、ルート、Design、またはTest仕様が実質的に変わらない場合は、その場で直接回答します。

このようなケースでは、確認の手順を使用してはいけません。

そのポイントが設計に影響すると判明した場合は、通常の確認手順に進みます。

3. すでに根拠から確定できる内容を解決する

重要な未決定事項ごとに、確定済みのユーザーの選択、現在の会話の文脈、既存のタスク資料、用語集の文言、コード、ドキュメント、またはそれらの選択から導かれるリスクの低い機械的な帰結によって、回答がすでに確定しているかをまず確認します。

現在のコードベース、ドキュメント、または準拠すべき成果物ですでに決まっている情報を、ユーザーに尋ねてはいけません。まずそれらの情報源を使い、情報が存在しない、曖昧である、矛盾している、または意思決定に不十分な場合に限り、質問します。

デフォルト、「妥当なデフォルト」、一般的な慣行、慣例、フレームワークの習慣、実装上の都合、アシスタントの好み、アシスタントの直感は、すでにある確定的な根拠ではありません。これらを使って重要な意思決定ポイントを暗黙に解決してはいけません。

これらは、選択肢を提示したり推奨案を示したりする際の参考にはできます。その場合、ユーザーの確認または回答によって意思決定を確定します。

ユーザーの表現、用語集の文言、タスク資料、コードの間に矛盾がある場合は、それを明示して提示します。

2つの概念が同じものか、別のものか、異なるルールに従うかを左右する区別は、重要なものとして扱います。

境界がすでに確定している場合、正確な名前、表現、ラベル、フィールド名、列挙型名、その他変更コストの低い設計上のテキストについて確認を求めてはいけません。設計成果物が存在する場合はDesignに記載し、存在しない場合はその場で対応します。

Designの作成またはレビューで新たな重要な未決定事項が見つかった場合は、続行する前に確認に戻ります。

4. 確定した意思決定を確認する

確定した意思決定について、会話上で明示すべき選択に限り、チャットで確認します。成果物への保存は「結果の保存先」に従って処理します。

ユーザー自身が行った選択、ユーザーの入力から機械的に導かれる結果、その後の確認が依存する選択、または曖昧さの軽減につながる選択には、この方法を使います。確信度やモデルの推論は追加しません。次の形式を使います。

記録しました：。

意思決定を記録したら、直ちに続行します。

確定した意思決定を意思決定のまとめに含めてはいけません。

5. 未確定の決定事項について提案するか、質問する

ユーザーや既存の資料によって決まっていない重要な決定事項については、次のいずれかを選びます。

• 提案する決定事項の一覧：エージェントが明確な選択肢を提案でき、ユーザーの確認や同意だけで十分な場合に使用します。
• 確認質問：選択肢を決める前に、ユーザーからの入力が必要な場合に使用します。

提案する決定事項の一覧には、提案する決定事項を最大6件まで含めることができます。決定事項には、一覧内で1から始まる連番を付け、番号は6を超えないようにします。提案する決定事項ごとに、次の形式を使用します。

Decision 1: <簡潔な回答> (%) Reason: <簡潔な理由>

Decision 2: <簡潔な回答> (%) Reason: <簡潔な理由>

どちらの行も簡潔にします。各 Decision <N>: 行には、提案する回答を記載します。

決定事項の一覧を提示した後、ユーザーに確認、質問、または異議を述べるよう求めてから、返答を待ちます。

確認質問には、必ず選択肢をすべて記載します。次の形式を使用します。

Question: <簡潔な質問> Recommended option: (%) Options:

• A. <選択肢の簡潔な概要>
• B. <選択肢の簡潔な概要>
• C. <選択肢の簡潔な概要>

Reason: <簡潔な理由>

確認質問では、以下のルールに従います。

• Recommended option: には、推奨する選択肢の文字と確信度だけを記載します。
• 選択肢の概要と説明は、Options: と Reason: にのみ記載します。
• 選択肢の行は - <LETTER>. <概要> の形式にします。
• 最後の選択肢の行と Reason: の間には空行を入れます。
• 選択肢の行に確信度を記載しないでください。
• はい／いいえの選択肢では、A. はい、B. いいえ のような概要を使用します。

Options: を含む返答を送信する前に、次の点を確認します。

• Recommended option: の行が正確に Recommended option: <LETTER> (<N>%) の形式になっていること。
• 推奨する文字が選択肢の一覧に含まれていること。
• 選択肢の行が正確に - <LETTER>. <概要> の形式になっていること。
• 最後の選択肢の行と Reason: の間に空行があること。
• 選択肢の行に確信度が含まれていないこと。

ユーザーが提示された選択肢を明確に承認した場合は、その選択を記録します。

決定事項のスクリーニング結果

必須の決定事項のスクリーニングでは、重要な決定事項ごとに、次の結果のみを出すことができます。

• 判断根拠によって解決済み。必要に応じて確認を得る。
• スクリーニングの結果、その選択が重要な未確定の決定事項の定義に該当せず、このスキルの下でユーザーの確認も不要であるため、確認対象外。
• ユーザー確認待ち。提案する決定事項の一覧に含める。
• ユーザー回答待ち。確認質問をする。
• 解決範囲外のため保留し、解決範囲の定義に沿って差し戻す。

確認対象外となる結果には、実質的な意味が確定済みの表現やラベルの選択肢、およびすでに確定した範囲、動作、制約、経路、受け入れ要件を実装するだけの設計／テスト上の選択肢が含まれます。

確認対象外の選択肢は、判断根拠でも、ユーザーが確認した決定事項でもありません。呼び出し元のワークフローに戻し、そのワークフローが管理する場合にのみ記録します。

解決済みおよび確認対象外の結果に限り、依存する最終コンテンツをただちに作成できます。ユーザー確認待ちまたはユーザー回答待ちの結果は、依存する最終コンテンツを作成する前に解決する必要があります。保留の場合は、呼び出し元のワークフローに制御を戻します。

明確化の労力に関する質問

明確化の労力は、提案する決定事項のまとまりと、ユーザーや既存の資料によって決まっていない事項についての明確化の質問とのバランスを調整します。質問に選択肢を含めるかどうかは調整しません。明確化の質問には、すべて選択肢を含めます。また、何が重要な未決定事項に当たるかや、最終結果を保持する必要性も変わりません。

明確化に実質的なステップが2回を超えて必要になりそうな場合、または決定の範囲が広く、詳細の決定にユーザーの意向を反映することが重要な場合に限り、明確化の労力に関する質問をしてください。明確化が実質的なステップ2回以内に終わる見込みの場合は、質問しないでください。

実質的な明確化のステップとは、次のいずれかです。

• 1つの決定事項のまとまり、または
• 議論や作業項目についての実質的な質問1つ。

明確化の労力に関する質問をする前に、何を明確にする必要があるのか、その理由とともに簡潔に説明してください。この範囲の説明と、明確化の労力に関する質問は、実質的なステップには数えません。

明確化の労力に関する質問は、実質的なステップの前でも、1つ以上のステップの後でも構いません。以下はすべて有効な順序です。

• 明確化の労力に関する質問、1、2、3
• 1、明確化の労力に関する質問、2、3
• 1、2、明確化の労力に関する質問、3、4、5

明確化の労力に関する質問は、必須の選択肢形式の特別なケースです。次の固定テンプレートを使用し、推奨する選択肢、確信度、理由のみを変更してください。

質問：この明確化のセッションに、どの程度関与したいですか？ 推奨する選択肢：<A/B/C/D>（%） 選択肢：

• A. 低い労力：安全な場合は、提案された決定事項のまとまりを優先し、ユーザーの入力が必要な場合にのみ質問します。
• B. 通常の労力：明確な選択肢を提示し、不確実な場合や好みによって判断が分かれる場合に質問します。
• C. 高い労力：不確実な場合、または最も重要な決定事項の選択に関わる場合に質問し、明快な選択には決定事項のまとまりを使います。
• D. 網羅的：重要な未決定事項をすべて質問し、決定済みの事項はそのまま記録します。

理由：<推奨する選択肢の簡潔な理由> 「質問を減らして」「質問を増やして」「重要な決定事項をすべて質問して」と伝えることで、後から変更できます。

状況に最も適した選択肢を推奨してください。別の選択肢を推奨する強い理由がない場合は、通常の労力を推奨してください。

明確化の労力に関する質問をしたら、ユーザーの次の返信を待ってください。その返信で質問に答えていない場合は、推奨した選択肢を採用し、その旨を伝えてから続けてください。

一度設定した明確化の労力は、ユーザーが変更しない限り、現在の明確化の一連のやり取りに適用されます。同じチャットセッション内で後から明確化が必要になった場合、質問する必要があれば再度質問してください。最後に選択された設定、または別の選択肢を推奨しても構いません。新しい明確化の一連のやり取りでは、以前の労力設定を有効なものとして黙って再利用しないでください。ユーザーが設定を記憶するよう求めた場合は、利用可能なメモリやプロジェクトの指示を使用できます。

低い、通常、高い、網羅的は、唯一の設定ではなく、連続した尺度上の基準点として扱ってください。「質問を減らして」「質問を増やして」は、その尺度に沿った相対的な調整として解釈してください。「重要な決定事項をすべて質問して」は、網羅的として解釈してください。

「もっと詳しく問いただして」「もっと徹底的に問いただして」「あまり問いたださないで」「軽めに問いただして」のような自然な表現は、関与の度合いを調整する指示として解釈しても構いません。ただし、ユーザー向けの文章でこれらの表現を案内しないでください。

明確化時の手順

未決事項は、重要度と不確実性の高い順に選びます。選んだ項目は、深さ優先で検討します。

実質的な明確化の各ステップでは、次のいずれかを必ず1つだけ提示します。

• 1つの決定事項のまとまり、または
• 1つの明確化の質問。

依存する決定事項のまとまりを提示する前に、質問をしてはいけません。 決定事項のまとまりと同じ応答内で、新たな質問をしてはいけません。

応答に明確化の質問または決定事項のまとまりを含める場合は、その質問または決定事項のまとまりをメッセージの末尾に置きます。必要な背景情報、根拠、説明、状況は、その前に記載します。決定事項のまとまりの後に続けてよいのは、短い確認・質問・異議の促しだけです。

ユーザーの確認または合意が必要な、エージェントが提案する決定事項にのみ、番号付きの Decision <N>: エントリを使用します。ユーザーがすでに決定した選択肢や、既存の資料で確定している事項には使用しません。

結果の保存先

明確化には、それを管理する成果物がある場合と、チャット内でのみ扱う場合があります。

次の保存ルールに従います。

• タスク管理下の明確化：最終的に確定した決定事項をタスク成果物に保存します。
• ADR 作業中の明確化：最終的に確定した決定事項を ADR に保存します。
• チャット内のみの明確化：ユーザーが保存先を指定するまで、決定事項はチャット内にとどめます。チャット内のみの明確化の最後に、結果を保存するか、保存する場合はどこに保存するかを尋ねます。

チャット内のみの明確化では、永続的な保存先を作成、選択、推測してはいけません。結果をどこかに記録する前に、ユーザーに保存先を尋ねます。

管理する成果物がある場合は、確定した最終内容のみを保存します。未解決の質問、確信度、一時的なメモは保存しません。

タスク成果物では、次のようにします。

• 最終的な決定事項は、タスクファイルの Analysis またはチャット内のみのタスクの Scope に記載します。
• セクションの順序と各種情報に関するルールは、spec-loop-plan-task/common-task-guidance.md に従います。
• どちらの形式でも、最終的な決定事項には同ファイルの Analysis の箇条書きルールを適用します。

ADR では、最終的に確定したすべての内容を Analysis に押し込めてはいけません。 spec-loop-write-adr/adr-format.md に従い、次のようにします。

• 決定前の事実は Context に記載します。
• 妥当な競合案は Alternatives に記載します。
• 選択した結果は Decision に記載します。
• 選択した決定を裏付ける、ADR に関連する理由だけを、簡潔な箇条書きとして Analysis に残します。

ADR では、妥当な代替案を Alternatives に記載し、Analysis 内で重複させません。

このスキルは、複数領域にまたがって適用されます。決定事項が確定し、管理する成果物がある場合は、上記の適切なセクションを更新し、管理する成果物内で影響を受けるすべてのセクションも更新します。

明確化によって共有ドメイン用語が解決または変更された場合は、アクティブなタスクが存在するか、準備中であれば、必要な用語集の更新をそのタスクに記録します。

タスク管理下の作業では、それが危険な状態になる前に、確定した最終状態をチャット内だけにとどめず、タスクファイルの保存先へ反映します。また、制御を戻す前に、必ず確定した最終状態を同期します。このルールは、単独のチャット内のみの議論をタスク管理下の作業に変えるものではありません。

終了

呼び出し元のワークフローに作業を戻す前に、次の点を確認します。

• 引き継ぐ作業項目の範囲に、重要な未決事項が残っていないこと。
• 用語集の不整合とコード・ドキュメント間の矛盾が解決されているか、明示的に示されていること。
• 該当する場合、必要な用語集の更新が記録されていること。
• 管理する成果物が、最終的に確定した状態と一致していること。