ask-user

ユーザーに確認 — 選択ゲートパターン

契約

• 2〜4 個の選択肢を提示します（それ以上は不可。4 個を超えると選択に迷い始めます）。
• 必ず抜け道（スキップ、キャンセル、または「どれでもない」）を含めます。
• 選択肢を提示した直後に、そのターンを停止します。後続のツール呼び出し、先回りしたアクション、デフォルトの選択肢での続行は行いません。
• ユーザーの応答が次のターンを開始します。簡潔に応答を受け止めてから、選択に応じて分岐します。
• 1 メッセージにつき質問は 1 つだけです。選択ゲートを複数重ねてはいけません。
• 選択肢のラベルだけで内容がわかるようにします。「選択肢 1」ではなく、動作を表す動詞と短い補足を使います。

これは何か

2〜4 個の選択肢をユーザーに提示し、応答があるまで実行を停止するための形式化されたパターンです。GBrain を搭載したあらゆるエージェントでユーザー入力を必要とする際の標準的な方法です。

これは従来の async/await ではありません。LLM エージェントでは、「ゲート」とは次のことを意味します。

1. 選択肢（ボタンまたは番号付きの項目）を提示する
2. 現在のターンを明示的に停止する（続行しない）
3. ユーザーの応答が次のターンを開始する
4. 応答を読み取り、それに応じて分岐する

使用する場面

• 複数の解釈が妥当な、曖昧なリクエスト
• 破壊的な操作（一括削除、上書き）
• 分類や振り分けの判断（「どこに入れますか？」）
• 優先順位の判断（「最初にどれを行いますか？」）
• 初期フェーズのゲート（「次のインポート元に進む準備はできていますか？」）
• 誤ったデフォルトの選択によって多くの作業が無駄になる、あらゆる分岐

使用しない場面

• 明確で曖昧さのない指示 → そのまま実行します
• 影響の小さい判断 → 最善の選択肢を選び、その旨を伝えます
• 誤った選択より遅延のほうが大きな損失につながる、時間に追われる操作
• ユーザーがすでに希望を伝えている場合

選択肢の提示方法

プラットフォームに依存しない形式（どこでも使用可能）

番号またはラベル付きの選択肢を添えて、明確な質問を提示します。

🔀 **How should I handle this?**

[context about the decision — 1-3 lines max]

1. **Option A** — short description
2. **Option B** — short description
3. **Option C** — short description
4. **Skip** — do nothing for now

インラインボタンを使用する場合（Telegram、Discord、Slack）

プラットフォームがインタラクティブなボタンに対応している場合は、ボタンを使用します。

{
  "message": "🔀 **How should I handle this?**\n\n<context>",
  "buttons": [
    { "label": "Option A — description", "value": "option_a" },
    { "label": "Option B — description", "value": "option_b" },
    { "label": "Skip", "value": "skip" }
  ]
}

clarify ツールを使用する場合（OpenClaw エージェント）

一部の OpenClaw エージェントには、選択肢をネイティブに提示する組み込みの clarify ツールがあります。

clarify(
  question: "How should I handle this?",
  choices: [
    "Option A — description",
    "Option B — description",
    "Option C — description",
    "Skip for now"
  ]
)

制約

• 選択肢は最大 2〜4 個です。 4 個を超えると、選択に迷ってしまいます。
• ラベルだけで内容がわかるようにします。 ユーザーが文脈を読み直す必要があってはいけません。
• 必ず抜け道を含めます。 最低でも最後の選択肢として「スキップ」または「キャンセル」を含めます。
• 1 メッセージにつき質問は 1 つだけです。 選択ゲートを複数重ねてはいけません。

ゲートの方法（重要）

選択肢を提示した後は、必ずそのターンを停止します。 次のことをしてはいけません。

• ❌ 「決めている間に、こちらを始めておきます」などと続ける
• ❌ デフォルトを選んで続行する
• ❌ ユーザーの応答前にフォローアップメッセージを送る
• ❌ ユーザーがどの選択肢を選ぶか、勝手に想定する

代わりに、次のようにします。

• ✅ 応答を待っていることを短く伝えて、メッセージを終える
• ✅ 停止します。完全に停止します。それ以上ツールを呼び出してはいけません。

応答の処理方法

ユーザーが応答したら：

1. 応答を読み取ります — ボタンのクリック、番号、またはテキスト
2. 簡潔に受け止めます — 「了解しました。選択肢 A で進めます。」
3. 選択された経路に分岐して実行します
4. 意図が不明確な場合は、もう一度尋ねます

テキストでの応答の処理

ユーザーがボタンをクリックせずに入力することがあります。適切に対応してください。

• 「最初のもの」／「A」／「1」→ 最初の選択肢に対応付ける
• 「マージ」→ 選択肢のラベルや値と曖昧一致させる
• 「やっぱり、どれでもない」→ 別の選択肢を提示するか、希望を尋ねる
• 無関係なメッセージ → ユーザーが別の話題に移ったものとして、ゲートを解除する

書式ガイドライン

質問行の絵文字プレフィックス

判断の種類を示します。

• 🔀 振り分け／分類の判断
• ⚠️ 破壊的／リスクのある操作
• 🎯 優先順位／トリアージの判断
• 💡 創造的／戦略的な分岐
• 📋 ワークフロー／プロセスの選択
• 🔐 認証情報／セキュリティの判断

コンテキストブロック

最大 1〜3 行です。ユーザーが 5 秒以内に判断内容を理解できるようにします。

ボタン／選択肢のラベル

形式：動作を表す動詞 — 短い補足

• ✅ 「マージ — 既存のページと統合」
• ✅ 「新規作成 — 別の会議ページを作成」
• ❌ 「選択肢 1」
• ❌ 「ここをクリックして、既存の brain ページにコンテンツをマージ」

例

初期フェーズのゲート

📋 **Phase 2: Google Contacts**

I can import your Google Contacts to seed the people/ directory.
This creates a brain page for each real contact (~200 pages).

1. **Import via ClawVisor** — secure credential gateway
2. **Import via direct OAuth** — simpler, agent holds tokens
3. **Import from Google Takeout export** — offline, from file
4. **Skip** — move to the next phase

分類の判断

🔀 **Where should this go?**

Meeting notes from call with Jane Smith. She already has a page at
people/jane-smith.md and there's a deal page at deals/acme-corp.md.

1. **Merge into Jane's page** — add to her timeline
2. **Add to Acme deal page** — this was primarily a deal discussion
3. **New meeting page** — standalone at meetings/2026-01-15-jane-acme.md
4. **Skip** — don't file this

破壊的な操作

⚠️ **About to delete 847 stale cache files (2.3 GB)**

These haven't been accessed in 90+ days. They can be re-fetched
but that takes ~4 hours.

1. **Delete them** — free up space now
2. **Archive first** — upload to cloud storage, then delete
3. **Keep them** — no changes
4. **Show me the list** — let me review before deciding

他のスキルとの連携

このパターンは、次のスキルで使用されています。

• cold-start — 各インポート元のフェーズゲート
• ingest — 曖昧なコンテンツの振り分け判断
• enrich — エンティティページの統合と新規作成の判断
• brain-ops — 保存先の判断
• meeting-ingestion — 議事録の保存先
• archive-crawler — スキャンと完全な取り込みのゲート

判断ポイントでユーザーの入力が必要な新しいスキルを作成する場合は、 新しいパターンを作るのではなく、このパターンを参照してください。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または通知ブロックについては、エージェントオペレータープロトコルに従ってください。このスキル固有の対応は次のとおりです。

• gbrain の呼び出しが終了コード 3（confirmation_required）で終了した場合、または fix.next が ask_user の場合：このスキルがゲートです。[SHOW USER] ブロックまたは user_message を選択肢としてそのまま伝え、ユーザーの回答を待って停止してください。
• ユーザーが「いいえ」と答えた場合、または回答しなかった場合：そのステップをスキップしたと報告してください。先に進むために、ユーザーに代わって --yes や --max-usd を渡してはいけません。

アンチパターン

• 選択肢を提示した後も同じターンを続けること。「決めている間に、こちらを始めます……」 ではゲートの意味がなくなります。停止して、待ってください。次に何が起きるかをユーザーが決めることが、このパターンの目的です。
• **デフォルトを選んで、黙って先に進むこと。**質問するほど重要なら、回答を待つだけの価値があります。黙ってデフォルトを選ぶと、次に質問するときの信頼が損なわれます。
• **選択肢が4つを超えること。**選択に迷うのは現実に起こります。選択肢をまとめるか、要約するか、段階的な質問に分けてください。
• **回避手段がないこと。**すべての選択ゲートで、ユーザーが辞退できるようにしてください。「該当なし」／「スキップ」／「キャンセル」は必須です。
• **1つのメッセージに複数の選択ゲートを詰め込むこと。**ユーザーが1ターンで回答できる質問は1つだけです。質問が複数あるゲートでは、回答が一部にとどまるか、すべて回答されずに終わります。
• 選択肢のラベルが分かりにくいこと。「選択肢1」では、文脈を読み直す必要があります。「既存のページに統合」のように、内容が明確なラベルにしてください。
• **重要度の低い判断について質問すること。**間違った回答によるコストがないなら、最善の選択肢を選び、その旨を伝えてください。ゲートは、やり直しのコストが大きい分岐に限って設けてください。

出力形式

このスキルの「出力」は、次のような構成の選択ゲートメッセージそのものです。

{emoji-prefix} **{question}**

{1-3 lines of context}

1. **{Option A label}** — {short qualifier}
2. **{Option B label}** — {short qualifier}
3. **{Skip / Cancel}** — {what skipping means}

これを出力したら、そのターンを終了してください。その後のツール呼び出し、先回りしたアクション、ユーザーの応答前のフォローアップメッセージは行いません。ユーザーの応答によって次のターンが始まり、呼び出し元のスキルは選択された選択肢に応じて分岐します。