Error Message Explanation Intent Query Rewrite Prompt Template

This prompt is designed for developer tools, platform support, and operations RAG systems that must handle error message pastes or error code references. Its job is to detect when a user is submitting an error for diagnosis, normalize the error signature, and rewrite the query to retrieve root-cause explanations, common fixes, and version-specific resolution steps. The ideal user is an RAG architect or search engineer building retrieval for a support copilot, internal platform assistant, or developer documentation site where users frequently paste stack traces, log snippets, or error codes.

Use this prompt when your retrieval system needs to distinguish error-diagnosis intent from general how-to or conceptual questions. The prompt expects a raw user input containing an error message, code, or symptom description. It outputs a normalized error identifier and a retrieval query that preserves the error signature while expanding for resolution context—such as adding terms like 'troubleshooting', 'root cause', 'fix', or version-specific qualifiers. Do not use this prompt for general technical Q&A where the user is asking for definitions, tutorials, or API references without an error signature. It is also unsuitable for non-technical support domains where error codes are not the primary retrieval signal.

Before wiring this into production, ensure your retrieval corpus contains diagnostic content: known issues, runbooks, changelogs, and resolution guides. The prompt alone cannot compensate for a knowledge base that lacks fix histories. Pair it with metadata filters for version, service, and environment if your platform supports hybrid search. Always evaluate whether the rewritten query surfaces documents with actionable resolution steps rather than generic error code definitions. If the error signature is ambiguous or the confidence is low, route to a human clarification step rather than returning irrelevant results.

This prompt template is designed to sit between a user's raw input and your retrieval system. Its job is to detect when a user has pasted an error message, stack trace, or error code, and to rewrite that input into a retrieval query optimized for finding root-cause explanations, common fixes, and version-specific resolution steps. The template uses square-bracket placeholders for all dynamic inputs, making it straightforward to integrate into a prompt assembly pipeline where application code injects the current user message, any available session context, and your desired output schema.

textCopy
You are a query rewriter for a developer support retrieval system. Your task is to analyze the user's input, determine if it contains an error message, error code, stack trace, or crash report, and rewrite it into an optimized retrieval query.

[CONTEXT]

[EXAMPLES]

INPUT:
[USER_INPUT]

INSTRUCTIONS:
1. Determine if the input contains an error message, error code, stack trace, or crash report. If it does not, set "intent_detected" to false and return an empty "rewritten_query".
2. If error intent is detected, extract and normalize the primary error identifier. This could be an error code (e.g., "ERR_MODULE_NOT_FOUND"), an exception type (e.g., "NullPointerException"), or a distinctive message fragment.
3. Rewrite the query to retrieve diagnostic content. The rewritten query must:
   - Preserve the exact error identifier when one exists.
   - Expand with resolution-oriented terms such as "fix", "solution", "root cause", "workaround", or "troubleshoot".
   - Include relevant context hints extracted from the error: framework, language, library, or environment if mentioned.
   - Not introduce hallucinated error codes or assume a specific fix.
4. Output the result in the following JSON structure.

[OUTPUT_SCHEMA]
{
  "intent_detected": boolean,
  "error_identifier": string | null,
  "error_type": "error_code" | "exception_type" | "message_fragment" | "stack_trace" | "crash_report" | null,
  "extracted_context": {
    "language": string | null,
    "framework": string | null,
    "library": string | null,
    "environment": string | null
  },
  "rewritten_query": string,
  "confidence": number  // 0.0 to 1.0
}

[CONSTRAINTS]
- Do not fabricate error codes or assume a specific root cause.
- If the error identifier is ambiguous, note the ambiguity in the rewritten query rather than guessing.
- Preserve version numbers if present in the input.
- The rewritten query should be a single string suitable for a keyword, vector, or hybrid search backend.

To adapt this template, start by populating the [CONTEXT] placeholder with any session history or user environment metadata your application already knows—such as the user's declared tech stack or recent conversation turns. The [EXAMPLES] placeholder should contain one to three few-shot demonstrations showing both positive cases (error messages that should be rewritten) and negative cases (general questions that should return intent_detected: false). The [OUTPUT_SCHEMA] block is already structured for direct JSON parsing; validate the output against this schema in your application layer before forwarding the rewritten_query to your retrieval backend. If the confidence score falls below a threshold you define (e.g., 0.7), route the original query to a fallback retrieval path or flag it for human review. For high-stakes production systems where incorrect retrieval could lead to applying a wrong fix, always log the full input-output pair and consider requiring human approval before executing any automated remediation steps surfaced by the retrieved documents.

This prompt is designed as a pre-retrieval transformation step in a developer tool or platform support RAG system. It should be invoked after user input is received but before any vector, keyword, or hybrid search query is executed. The harness must pass the raw user message as [USER_INPUT] and, optionally, any available session or environment context as [CONTEXT] (such as the user's detected programming language, framework version, or recent error history). The model's output is a structured JSON object containing a normalized_error_identifier and a retrieval_query. The normalized_error_identifier is used for exact-match lookups in a known-error database, while the retrieval_query is dispatched to the primary semantic search index.

To wire this into an application, implement a lightweight API endpoint or middleware function that accepts the user's query string. First, perform a quick client-side check: if the input does not contain patterns resembling a stack trace, error code, or exception message (e.g., lacks terms like Error, Exception, Traceback, or structured codes like EACCES), skip this prompt to save latency and fall back to a default retrieval query. If the input passes the heuristic, call the LLM with this prompt template. Parse the JSON response and validate that both fields are non-empty strings. If validation fails, log the raw output and fall back to using the original user query for retrieval. On success, execute a two-pronged retrieval: an exact filter query on a metadata field for the normalized_error_identifier and a semantic search using the retrieval_query. Merge and deduplicate results before passing them to the answer generation step.

For production observability, log the original user input, the normalized error identifier, the rewritten retrieval query, and the count of results returned from each retrieval path. This data is critical for debugging retrieval failures and for evaluating the prompt's performance over time. Set up an evaluation pipeline that periodically samples production traces and checks two key criteria: first, that the normalized_error_identifier correctly preserves the core error signature (e.g., TypeError is not rewritten to ReferenceError), and second, that the retrieval_query retrieves documents containing root-cause analysis or resolution steps, not just generic documentation. If the system is high-stakes (e.g., production incident response), route a sample of rewritten queries for human review before they are used to generate answers, especially when the confidence in error normalization is low or the error is novel.