Disambiguation Dialogue Prompt Template

This prompt template is for conversational AI builders who need a system to manage a multi-turn clarification loop. Use it when an initial user input is ambiguous, underspecified, or contains conflicting signals that prevent confident routing or task execution. The prompt instructs the model to act as a clarification agent that asks targeted questions, interprets user responses, updates its internal confidence, and decides when sufficient clarity is achieved to proceed. This is not a single-turn classification prompt. It is a dialogue manager designed to be called repeatedly within a stateful conversation loop.

The ideal deployment environment is a stateful application that maintains a conversation_history array and a clarity_state object across turns. Your application must inject the original ambiguous input, the history of questions and answers, and the current confidence assessment into each call. The prompt expects to receive a structured [CLARITY_STATE] containing the original intent hypotheses, their confidence scores, and a list of unresolved ambiguities. It returns a decision object: either a clarification_question to ask the user or a resolved_intent payload ready for downstream routing. Do not use this for one-shot disambiguation where no follow-up is possible, or for high-stakes decisions where a wrong interpretation before clarification would cause irreversible harm—those scenarios require a hard escalation to a human reviewer before any automated action is taken.

Before implementing this prompt, ensure you have defined a maximum turn limit and a terminal escalation path. A clarification loop that never converges degrades user experience and wastes inference costs. Your application harness should enforce a hard stop after a configurable number of turns (typically 3-5), at which point the system must escalate to a human or route to a general fallback queue with a note that clarification was exhausted. Additionally, instrument the loop with logging that captures each turn's confidence delta, the specific question asked, and the user's response. This trace data is essential for evaluating the prompt's resolution efficiency and identifying patterns where the model asks redundant or unhelpful questions. The companion eval checks in this playbook will help you measure resolution rate, average turns to clarity, and escalation frequency.

This prompt template is the core instruction set for a disambiguation agent. It is designed to be called on every turn of a clarification dialogue, with the conversation history and current state injected at runtime. The agent's job is not to answer the user's underlying request, but to ask the minimum number of targeted questions needed to resolve ambiguity, update its internal confidence, and decide when sufficient clarity has been achieved to hand off to a downstream routing or execution system. The template uses square-bracket placeholders for all dynamic inputs, making it ready for direct integration into an application harness.

markdownCopy
You are a clarification agent. Your only job is to resolve ambiguity in user requests before they are routed to a specialist. You do not fulfill the request yourself.

## Current State
- Ambiguity Type: [AMBIGUITY_TYPE]
- Ambiguous Spans: [AMBIGUOUS_SPANS]
- Current Confidence Score: [CONFIDENCE_SCORE]
- Questions Asked So Far: [QUESTIONS_ASKED_COUNT]
- Max Questions Allowed: [MAX_QUESTIONS]

## Conversation History
[HISTORY]

## Instructions
1. Analyze the conversation history and the latest user input to determine if the ambiguity has been resolved.
2. If the ambiguity is resolved, output a final structured object with `status: "resolved"`, a clear `resolved_intent`, and your final `confidence_score`.
3. If the ambiguity is not resolved and you have not exceeded [MAX_QUESTIONS], generate exactly one targeted, concise clarification question designed to resolve the specific uncertainty in [AMBIGUOUS_SPANS]. Output `status: "clarifying"`.
4. If the ambiguity is not resolved and you have reached [MAX_QUESTIONS], do not ask another question. Output `status: "max_turns_reached"` with your best-effort `resolved_intent` and a low `confidence_score`.
5. Never repeat a question you have already asked.
6. Do not answer the user's underlying request or provide any information beyond the clarification dialogue.

## Output Schema
You must respond with a valid JSON object matching this schema:
{
  "status": "clarifying" | "resolved" | "max_turns_reached",
  "clarification_question": "string | null",
  "resolved_intent": "string | null",
  "confidence_score": 0.0-1.0,
  "reasoning": "string"
}

To adapt this template, replace the placeholders with live data from your application state. [AMBIGUITY_TYPE] and [AMBIGUOUS_SPANS] should be populated by an upstream ambiguity detection prompt. [CONFIDENCE_SCORE] should be updated after each user response by re-evaluating the dialogue. [MAX_QUESTIONS] is a critical safety parameter—set it based on your user experience tolerance (typically 2-4) to prevent infinite loops. The [HISTORY] placeholder should be injected as a formatted transcript of the dialogue so far. For high-stakes domains, ensure the final resolved_intent and confidence_score are logged and, if below a defined threshold, trigger a human review workflow before any action is taken.

This prompt is not a single API call. It is the core instruction set for a stateful dialogue loop managed by your application. The application owns the conversation state, turn counter, confidence history, and termination logic. The model's job is to decide the next action—ask a clarifying question, update confidence, or declare resolution—based on the accumulated dialogue context you provide. Your harness must enforce the loop boundaries: maximum turns, minimum confidence thresholds, and escalation timeouts. Without these guardrails, the dialogue can drift into unproductive cycles or premature routing.

Implement the loop as a finite state machine with four states: INIT, CLARIFY, RESOLVE, and ESCALATE. On first input, assemble the prompt with the user's original request in [USER_INPUT], an empty [DIALOGUE_HISTORY], and the current [CONFIDENCE_SCORE] set to 0.0. Parse the model's JSON response to extract action, clarification_question, updated_confidence, and resolution. If action is ask, append the question to dialogue history, present it to the user, capture their response, and loop back to CLARIFY with the updated history. If action is resolve and updated_confidence exceeds your configured threshold (typically 0.85 for high-stakes routing, 0.70 for general triage), transition to RESOLVE and route the clarified intent downstream. If action is escalate or the turn counter exceeds your maximum (start with 3 turns and tune from production data), transition to ESCALATE and hand off to a human queue with the full dialogue transcript. Validate every model response against your expected JSON schema before acting on it. A malformed response should trigger a retry with the same context, not a silent fallback.

Log every turn with a structured event: session_id, turn_number, model_action, confidence_before, confidence_after, user_response, and latency_ms. This trace data is essential for tuning your confidence thresholds and turn limits. Common failure modes to monitor: the model asking redundant questions already answered in prior turns, confidence scores that oscillate without converging, and premature resolution when critical disambiguation remains. Wire these metrics into your observability dashboard alongside an eval harness that replays production dialogues against your golden set of ambiguous inputs to measure resolution accuracy and average turns-to-resolve. Start with a fast, cost-effective model for the dialogue loop and reserve a more capable model for the final classification step once disambiguation is complete.