Query Intent Classification Prompt for Retrieval

This prompt is a routing control point, not a conversational interface. Its job is to inspect a user's raw search query and assign it to a single, predefined intent label from a controlled taxonomy. You need this when your retrieval system has multiple, distinct strategies—such as a vector store for semantic search, a BM25 index for keyword matching, a text-to-SQL engine for analytical queries, and a direct document lookup for known IDs—and choosing the wrong path degrades result quality or breaks downstream automation. The ideal user is a search engineer, AI architect, or platform developer who owns the retrieval pipeline and needs a deterministic, auditable classification step before any document fetching occurs.

The classification output must be a single, machine-readable label that maps directly to a function call, an index selection, or a query rewriter configuration. For example, a query like 'show me the Q3 revenue breakdown by region' should return the label analytical_query, which triggers SQL generation, while 'what is the return policy for electronics' should return policy_lookup, which triggers a filtered keyword search over a policy corpus. The prompt is designed to reject out-of-vocabulary queries by returning an out_of_domain label rather than hallucinating a plausible but incorrect intent. This is critical for production systems where a misclassified intent can silently route a user to the wrong index, producing irrelevant results with no visible error.

Do not use this prompt when the query itself is the final retrieval input without routing logic, when you need a conversational response, or when your system has only a single retrieval path. In those cases, the classification step adds latency and a potential failure point without providing architectural value. Also avoid this prompt for multi-turn dialogue state tracking; it is designed for single-turn query classification. If you need to maintain intent context across a conversation, pair this with a separate state management component. Before deploying, validate the taxonomy against real query logs to ensure coverage, define a confidence threshold below which queries are routed to a fallback strategy, and log every classification decision with the query, predicted label, and downstream retrieval path for debugging and evaluation.

This template provides a complete, copy-ready prompt for classifying user queries into exactly one intent label from your controlled taxonomy. It is designed to be dropped into a retrieval pipeline where the classified intent determines downstream search strategy, index selection, or retrieval parameters. The prompt enforces strict JSON output, handles ambiguous queries through an explicit abstention label, and includes a confidence score to enable threshold-based routing decisions in your application code.

textCopy
System: You are a query intent classifier for a retrieval system. Your job is to analyze the user's query and assign exactly one intent label from the provided taxonomy. You must return valid JSON only, with no additional text, commentary, or markdown formatting.

## Intent Taxonomy
[TAXONOMY]

## Classification Rules
1. Select the single best-matching intent label from the taxonomy above.
2. If the query is ambiguous, unclear, or does not clearly match any intent, use the label "[UNKNOWN_INTENT_LABEL]".
3. If the query contains multiple intents, select the primary or most specific intent.
4. Provide a confidence score between 0.0 and 1.0 reflecting how certain you are about the classification.
5. If confidence is below [CONFIDENCE_THRESHOLD], prefer the "[UNKNOWN_INTENT_LABEL]" label.

## Output Schema
Return only a JSON object with these exact fields:
{
  "intent": "<selected label from taxonomy>",
  "confidence": <float between 0.0 and 1.0>,
  "reasoning": "<brief explanation of why this intent was selected>"
}

## Examples
[EXAMPLES]

## Constraints
- Do not invent new intent labels.
- Do not return multiple intents.
- Do not wrap the JSON in markdown code fences.
- If the query is not in English, still classify based on semantic meaning.

User Query: [INPUT]

To adapt this template, replace [TAXONOMY] with your controlled list of intent labels and their descriptions. The [UNKNOWN_INTENT_LABEL] placeholder should be set to a specific label like unknown or out_of_scope that your routing logic can handle gracefully. The [CONFIDENCE_THRESHOLD] should match the threshold you use in your application code for rejecting low-confidence classifications. The [EXAMPLES] section is critical for ambiguous or boundary queries—include at least 3-5 few-shot examples that demonstrate correct classification for queries that sit between two intents, contain domain-specific jargon, or are deliberately vague. The [INPUT] placeholder receives the raw user query at runtime. Validate every output against the schema before allowing it to influence retrieval decisions; a malformed JSON response or an invented intent label can silently break downstream routing logic.

The query intent classification prompt is a pre-retrieval gate. It runs before any vector, keyword, or hybrid search query is executed. Its job is to read the raw user query and output a structured intent label that downstream retrieval logic uses to select indexes, adjust weights, apply metadata filters, or choose a completely different retrieval strategy. This prompt is not a chatbot response generator—it is a classification component inside a retrieval pipeline. Wire it as a synchronous step that blocks retrieval until a valid intent label is returned, with a hard timeout and a safe default fallback intent (e.g., general_search) if classification fails or times out.

Integration pattern: Place this prompt inside a lightweight API endpoint or a queue worker that accepts { "query": "..." } and returns { "intent": "...", "confidence": 0.92 }. The retrieval service reads the intent field and routes accordingly. For example, a code_generation intent might route to a code-specific embedding index with higher k and a keyword boost, while a definition_lookup intent might route to a dense glossary index with strict metadata filtering on doc_type: definition. Validation is mandatory: reject any response where the intent field is not in your controlled vocabulary. If the model returns an unknown label or malformed JSON, log the raw output, increment a classification_failure metric, and fall back to the default retrieval path. Do not pass unvalidated labels to downstream systems.

Model choice and latency: Use a fast, cost-effective model for this classification step—GPT-4o-mini, Claude Haiku, or a fine-tuned small open-weight model running locally. The prompt is short, the output schema is tiny, and latency should stay under 300ms. If you are processing high-throughput query streams, consider batching classifications or caching frequent query-intent pairs with a TTL. Retries: if the model returns invalid JSON or an out-of-vocabulary label, retry once with a stricter prompt variant that includes the full list of valid labels and an explicit instruction to return only from that set. If the retry also fails, log the query and raw response for offline analysis, emit the fallback intent, and let the retrieval proceed. Never block the user on a classification failure.

Observability and eval: Log every classification decision with query, intent, confidence, model, latency_ms, and fallback_used as structured fields. This log becomes your evaluation dataset. Weekly, sample 200 classified queries and have a human reviewer or an LLM judge check whether the assigned intent matches the query. Track intent distribution drift—if code_generation suddenly drops from 15% to 2% of traffic, your classifier or your user base has changed. Multi-intent queries: when a query spans two intents (e.g., 'explain and give me a code example for X'), the prompt should be configured to return the primary intent plus an optional secondary_intents array. Your retrieval logic can then blend results from multiple indexes. If your retrieval system cannot handle multi-intent blending, constrain the prompt to single-intent output only and accept that some queries will be imperfectly routed.

What to avoid: Do not use this prompt to generate answers, summaries, or retrieval queries. It is a classifier, not a generator. Do not skip validation because 'the model usually gets it right'—one hallucinated intent label can route a query to the wrong index and produce irrelevant results that erode user trust. Do not add intents to the taxonomy without updating the prompt, the validation set, and the routing map simultaneously. A new intent label in the prompt with no corresponding retrieval path is a silent failure. Finally, do not treat intent classification as a one-time setup—query patterns change as your product evolves, and your intent taxonomy and routing rules must evolve with them.