Clarification Question Generation Prompt Template

This prompt is designed for the agent frontend pre-processing layer—the moment after a user submits an instruction but before any planning, tool selection, or execution begins. Its job is to detect ambiguity that would cause downstream errors and generate a minimal, ranked set of clarification questions. The ideal user is an AI engineer or product developer building an agent that interacts with end-users through a chat or command interface. You need this prompt when the cost of a wrong assumption is high: destructive actions, paid API calls, irreversible data mutations, or multi-step workflows where an early misunderstanding corrupts every subsequent step.

Use this prompt when the user's objective is underspecified in ways that matter for execution. Concrete triggers include: missing parameters for a function call, conflicting constraints in the same request, vague success criteria ('make it better'), ambiguous resource targets ('the production database' when multiple exist), or instructions that assume context the system does not have. Do not use this prompt for simple, fully-specified commands ('add 2+2'), for workflows where the system should make a reasonable default choice and proceed, or when the user has explicitly opted into autonomous mode with pre-authorized ambiguity resolution. Over-clarification creates friction; this prompt is for high-stakes ambiguity, not conversational completeness.

Before wiring this into your application, define your ambiguity budget: how many questions you are willing to ask per turn, and which ambiguity categories (missing parameters, conflicting constraints, vague success criteria, unverified resource targets) are in scope. The prompt produces ranked questions, but your application should enforce a hard cap on questions displayed to the user—typically 2–4. If the prompt returns more, your harness should select the top-ranked subset and log the rest for product improvement. Pair this prompt with the Assumption Inventory Generation and Pre-Flight Assumption Check playbooks to create a complete pre-execution gate: extract assumptions, flag low-confidence ones, and only then generate clarification questions for the critical unknowns.

This template generates a minimal set of clarification questions ranked by their impact on plan correctness. It is designed for agent frontends that receive ambiguous user instructions and must resolve uncertainty before committing to irreversible actions or expensive multi-step execution. The prompt forces the model to identify what is ambiguous, explain why it matters for downstream planning, and produce questions that are specific, answerable, and non-redundant. Use this template when user input is underspecified and the cost of wrong execution exceeds the cost of asking.

textCopy
You are a clarification specialist for an AI agent system. Your job is to analyze an ambiguous user instruction and generate the smallest set of targeted questions needed to resolve critical uncertainties before planning begins.

## INPUT
User Instruction: [USER_INSTRUCTION]
Available Context: [CONTEXT]
Available Tools and Capabilities: [TOOLS]
Operational Constraints: [CONSTRAINTS]
Risk Level: [RISK_LEVEL]

## INSTRUCTIONS
1. Identify every ambiguity in the user instruction that could cause the agent to produce a materially wrong plan. Consider:
   - Missing parameters required by available tools
   - Underspecified scope, boundaries, or success criteria
   - Implicit assumptions about data, permissions, or environment state
   - Ambiguous terms that have multiple valid interpretations in this domain
   - Missing constraints on cost, time, or resource usage
2. For each ambiguity, explain why it matters: what plan step would be affected and how a wrong assumption would manifest as an error.
3. Formulate one clear, specific question per ambiguity. Each question must:
   - Be answerable by the user without requiring technical knowledge of the agent's internals
   - Offer concrete options when the choice space is bounded
   - Avoid leading the user toward a particular answer
   - Not duplicate information already present in the context
4. Rank questions by impact: how much plan correctness depends on resolving this ambiguity. Use three tiers:
   - BLOCKING: Cannot produce any valid plan without this answer
   - HIGH_IMPACT: Plan would be structurally different depending on the answer
   - MEDIUM_IMPACT: Plan structure is stable but execution details would change
5. Eliminate any question that can be answered by inspecting the available context or tool outputs.
6. Limit output to at most [MAX_QUESTIONS] questions. If more ambiguities exist, include only the highest-impact ones and note how many were deferred.

## OUTPUT SCHEMA
Return a JSON object with this exact structure:
{
  "total_ambiguities_found": <integer>,
  "questions_generated": <integer>,
  "questions_deferred": <integer>,
  "questions": [
    {
      "id": "Q1",
      "question": "<clear question text>",
      "options": ["<option1>", "<option2>"] or null,
      "ambiguity_description": "<what is unclear and why it matters>",
      "affected_plan_area": "<which part of the plan depends on this answer>",
      "impact_tier": "BLOCKING|HIGH_IMPACT|MEDIUM_IMPACT",
      "default_assumption_if_skipped": "<what the agent would assume if user doesn't answer>"
    }
  ]
}

## CONSTRAINTS
- Do not ask questions that the user cannot reasonably answer.
- Do not ask questions where the default assumption is safe and the impact is low.
- Do not repeat questions that are already answered in the context.
- If the instruction is already sufficiently specific, return an empty questions array and explain why.
- For [RISK_LEVEL] of "high" or "critical", prefer over-asking to under-asking for BLOCKING and HIGH_IMPACT ambiguities.

To adapt this template, replace the square-bracket placeholders with your application's actual values. [USER_INSTRUCTION] should contain the raw user input. [CONTEXT] should include any session history, user profile data, or environmental state already known. [TOOLS] should list available tool names and their required parameters so the model can detect missing inputs. [CONSTRAINTS] should specify operational boundaries like time limits, cost budgets, or permission scopes. [RISK_LEVEL] accepts values like "low", "medium", "high", or "critical" and controls the model's bias toward asking versus proceeding with assumptions. [MAX_QUESTIONS] should be an integer (typically 3-5) to prevent overwhelming the user. The output schema is strict JSON suitable for direct consumption by an agent orchestrator. If your application cannot tolerate JSON parse failures, add a retry layer with schema validation before surfacing questions to the user.

The clarification question prompt operates as a synchronous gate in the agent planning pipeline. When a user submits an ambiguous instruction, the frontend routes the raw input through this prompt before any planning or tool selection occurs. The prompt returns a structured set of ranked questions, and the application must decide whether to present all questions, only high-impact questions, or none if the ambiguity is below a configured threshold. This decision logic lives in the application harness, not in the prompt itself.

Wire the prompt into a pre-processing step that fires after user input is received but before the planning module is invoked. The application should parse the model's JSON output and validate it against a strict schema: each question object requires an id, question_text, impact_on_plan, assumption_being_clarified, and rank field. Reject outputs that contain questions with duplicate IDs, missing impact justifications, or ranks that don't correspond to the impact ordering. If validation fails, retry once with the validation error appended to the prompt as feedback. After two consecutive failures, fall back to a safe default: present the user with a generic clarification prompt and log the failure for prompt debugging. Do not proceed to planning with unvalidated clarification output.

For production deployments, implement a question cap (default 3-5 questions) to prevent overwhelming the user. The harness should sort by rank and truncate to the cap before rendering. Log the full question set for observability even when truncated. If the top-ranked question has an impact score below a configurable threshold, skip clarification entirely and pass the original instruction to the planner with a low-confidence flag. For high-risk domains such as healthcare or finance, require human review of the generated questions before they are shown to the end user. Track metrics on question acceptance rate, ambiguity resolution rate (whether the user's answer actually changed the plan), and false-positive clarification requests where the original instruction was already sufficient.