Troubleshooting Intent Query Rewrite Prompt Template

This prompt is designed for support and operations RAG systems that must convert unstructured error descriptions, symptom reports, or 'something is broken' messages into precise diagnostic retrieval queries. The core job-to-be-done is intent-driven query reformulation: detecting that a user is in a troubleshooting or break-fix state, then rewriting their input to retrieve root-cause documentation, known issues, resolution steps, and diagnostic runbooks instead of generic definitions or marketing pages. The ideal user is an AI engineer or platform developer embedding this prompt into a retrieval pipeline for internal support tools, customer-facing help desks, or site reliability engineering (SRE) knowledge bases.

Use this prompt when your retrieval system serves a corpus that contains structured diagnostic content—error code databases, incident postmortems, runbooks, knowledge base articles with resolution steps, or version-specific bug trackers. The prompt expects a raw user query and optionally a session context or recent error logs. It outputs a rewritten query string optimized for diagnostic recall, plus a symptom-to-cause mapping hint that downstream retrieval logic can use to weight or filter results. Do not use this prompt when the user's intent is purely factual lookup, summarization, comparison, or procedural how-to without a diagnostic component; those intents require their own specialized rewrite templates to avoid polluting the retrieval with irrelevant document types.

Before wiring this into production, define the failure mode that matters most: false negatives in intent detection. If the prompt misclassifies a genuine troubleshooting request as a general question, the user receives unhelpful conceptual documentation. Mitigate this by pairing the prompt with an intent confidence scorer and a fallback retrieval strategy. For high-severity incidents where incorrect retrieval could delay resolution, route low-confidence outputs to a human triage queue. The next step is to copy the prompt template, map the placeholders to your system's inputs, and build a validation harness that checks whether retrieved documents contain diagnostic patterns—such as error codes, resolution steps, or root-cause language—rather than generic definitions.

This template transforms error descriptions, symptom reports, and malfunction narratives into retrieval-optimized queries for support and operations knowledge bases. It is designed for RAG systems where the same surface question—'Why is the dashboard slow?'—must be rewritten to surface diagnostic patterns, known incident records, and resolution runbooks rather than generic definitions or feature overviews. The prompt forces the model to extract the core symptom, hypothesize likely causes, and produce a query that targets root-cause documentation. Use this template when your retrieval corpus contains incident postmortems, bug databases, runbooks, and troubleshooting guides. Do not use it for general FAQ retrieval or how-to documentation where procedural steps are the primary intent.

textCopy
You are a diagnostic query rewriter for a technical support and operations RAG system. Your job is to take a user's error description, symptom report, or malfunction narrative and rewrite it into a retrieval query that will find root-cause documentation, known issues, resolution steps, and diagnostic runbooks.

## INPUT
User Query: [USER_QUERY]
System Context (optional): [SYSTEM_CONTEXT]
Known Error Catalog (optional): [KNOWN_ERRORS]

## OUTPUT SCHEMA
Return a valid JSON object with these fields:
{
  "original_query": "string (the user's exact input)",
  "detected_intent": "troubleshooting",
  "extracted_symptoms": ["string (observable symptom 1)", "string (observable symptom 2)"],
  "hypothesized_cause_categories": ["string (category 1)", "string (category 2)"],
  "rewritten_query": "string (the retrieval-optimized query)",
  "symptom_to_cause_mapping_hints": ["string (hint 1)", "string (hint 2)"],
  "diagnostic_signal_flags": ["error_code", "timeout", "crash", "degradation", "misconfiguration"],
  "confidence": 0.0_to_1.0
}

## CONSTRAINTS
- Preserve specific error codes, stack traces, version numbers, and timestamps from the original query.
- Expand vague symptom language ('broken', 'not working', 'slow') into observable, testable conditions.
- The rewritten query must target diagnostic content: root-cause analysis, incident records, resolution steps, and troubleshooting guides.
- Do not rewrite into a generic definition query or a how-to procedural query.
- If the user query contains no diagnostic signal, set confidence below 0.5 and flag for human clarification.
- If system context is provided, incorporate relevant component names, versions, and dependencies into the rewritten query.
- If a known error catalog is provided, match symptoms to known error patterns and include the error ID in the rewritten query.

## EXAMPLES
User Query: 'The payment service keeps returning 502 errors after the last deploy.'
Output:
{
  "original_query": "The payment service keeps returning 502 errors after the last deploy.",
  "detected_intent": "troubleshooting",
  "extracted_symptoms": ["502 Bad Gateway errors", "post-deployment onset"],
  "hypothesized_cause_categories": ["upstream service failure", "deployment regression", "proxy misconfiguration"],
  "rewritten_query": "payment service 502 Bad Gateway error root cause post-deployment regression upstream failure diagnosis resolution steps",
  "symptom_to_cause_mapping_hints": ["502 errors indicate upstream unreachable", "post-deploy timing suggests config or code change"],
  "diagnostic_signal_flags": ["error_code", "degradation"],
  "confidence": 0.92
}

User Query: 'What is a load balancer?'
Output:
{
  "original_query": "What is a load balancer?",
  "detected_intent": "troubleshooting",
  "extracted_symptoms": [],
  "hypothesized_cause_categories": [],
  "rewritten_query": "",
  "symptom_to_cause_mapping_hints": [],
  "diagnostic_signal_flags": [],
  "confidence": 0.1
}

## INSTRUCTIONS
1. Extract every observable symptom from the user query. Be specific: 'high latency' not 'slow', 'connection refused' not 'can't connect'.
2. Hypothesize 2-4 likely cause categories based on the symptoms. These guide retrieval toward root-cause documentation.
3. Construct the rewritten query by combining: extracted symptoms + hypothesized cause categories + diagnostic keywords (root cause, diagnosis, resolution, incident, postmortem, known issue).
4. Generate symptom-to-cause mapping hints that explain why each symptom points to the hypothesized causes.
5. Set diagnostic_signal_flags to any that apply from: error_code, timeout, crash, degradation, misconfiguration, data_loss, security_incident, dependency_failure.
6. Score confidence based on how clearly the user query expresses a diagnostic need versus a definitional or procedural request.
7. If confidence is below 0.5, leave rewritten_query empty and flag for human triage.

Adapt this template by replacing the example symptoms and cause categories with your domain's taxonomy. If your support corpus uses a controlled vocabulary for incident types—such as 'SEV1', 'SEV2', 'P0', 'P1'—add those as diagnostic signal flags. For multi-service architectures, extend the system context to include a service dependency map so the rewritten query can target the correct upstream or downstream component. The output schema is intentionally flat to simplify parsing in retrieval pipelines; if your search backend supports structured filters, add a metadata_filters object with fields like service_name, time_range, and incident_severity. Always validate that the rewritten query contains diagnostic keywords before sending it to retrieval—a query that returns only API reference pages is a failure mode indicating the intent detection missed the troubleshooting signal.

This prompt is designed to sit directly upstream of your retrieval engine in a support or operations RAG system. It accepts raw user error descriptions or symptom reports and outputs a structured payload containing a rewritten query and symptom-to-cause mapping hints. The primary integration point is a pre-retrieval transformation step: the user's message hits this prompt first, the output is parsed, and the rewritten_query field is sent to your vector, keyword, or hybrid search backend. The symptom_cause_hints field should be logged alongside the retrieval call for downstream debugging and evaluation, but it is not typically sent to the retriever unless you have a metadata-filtered index that can use it.

Wire this prompt into your application with a lightweight wrapper that enforces the output schema before retrieval proceeds. Parse the model response as JSON and validate that rewritten_query is a non-empty string and that symptom_cause_hints is an array of objects each containing symptom and possible_cause string fields. If validation fails, retry once with the same input and a stronger format reminder appended to the system message. If the second attempt also fails, log the raw output, fall back to the original user query for retrieval, and flag the interaction for review. For model choice, a capable instruction-following model with JSON mode support (such as GPT-4o, Claude 3.5 Sonnet, or equivalent) is recommended. Avoid models that struggle with structured output under 7B parameters unless you have fine-tuned them specifically for this task.

Observability is critical because query rewriting is a high-leverage step: a bad rewrite silently poisons retrieval quality. Log the original user query, the rewritten query, the symptom-cause hints, the model used, latency, and the validation status on every call. In your evaluation harness, pair these logs with retrieval-side metrics such as mean reciprocal rank (MRR) and recall@k for a golden set of troubleshooting queries. This lets you detect drift where rewrites become too generic or drop critical error signatures. For high-severity production systems where a missed root-cause document has operational consequences, consider adding a human review queue for low-confidence rewrites or for queries where the symptom-cause hints contain fewer than two extracted symptoms. The next step is to build a regression test suite using the evaluation criteria described in the main playbook: verify that retrieved documents contain diagnostic patterns (error codes, stack traces, resolution steps) rather than generic definitions, and that the symptom-to-cause mapping preserves the original error signature.