Common Cause Classification Prompt for Error Codes

This prompt is designed for support engineering and SRE teams who need to impose a consistent, structured taxonomy on a high volume of production error instances. The core job-to-be-done is transforming raw, unstructured error payloads—such as stack traces, log lines, or API error bodies—into a standardized root cause category with a calibrated confidence score. The ideal user is an engineer building an internal triage dashboard, automating runbook routing, or enriching incident alerts before they reach an on-call rotation. The required context is the raw error text itself; the prompt is engineered to work with the information present in the error payload and does not require deep system internals knowledge to be injected at runtime.

Use this prompt when you need to batch-process error logs to identify systemic failure patterns or when you are building a feedback loop from production errors back to your runbook library. It is particularly effective for handling ambiguous or multi-cause errors because it is instructed to surface uncertainty and propose multiple potential categories rather than forcing a single, potentially incorrect label. For example, a ConnectionTimeout error could stem from a network partition or an overloaded database; this prompt will output both possibilities with distinct confidence scores, allowing a downstream system or human reviewer to make the final determination. The output is a structured JSON object that includes the primary classification, alternative classifications, and a confidence score, making it directly ingestible by automated workflows.

Do not use this prompt for real-time incident response where latency is critical, as the model's inference time may introduce unacceptable delays in an active firefight. It is also unsuitable for errors where the root cause requires deep system internals knowledge not present in the error payload itself, such as a memory corruption bug that manifests as a generic segmentation fault. In such cases, the prompt will correctly identify the symptom but cannot infer the underlying cause without additional context. The next step after reading this section is to review the prompt template and understand how to adapt its input variables to your specific error format.

This prompt template is designed to be pasted directly into your AI orchestration layer. It instructs the model to act as a support engineer classifying production errors at scale. The model will analyze an error instance, map it to a predefined taxonomy, and return a structured classification with a confidence score and supporting rationale. Before using this template, ensure you have a well-defined error taxonomy and a set of representative examples for few-shot learning, which will significantly improve classification consistency.

codeCopy
SYSTEM:
You are a senior support engineer specializing in production error analysis. Your task is to classify a given error instance into a root cause category from a predefined taxonomy. You must provide a confidence score and a concise rationale for your classification. If the error is ambiguous or could belong to multiple categories, list the alternatives with their respective confidence scores and explain the ambiguity.

USER:
Classify the following error instance using the provided taxonomy and examples.

## Error Taxonomy
[TAXONOMY]

## Few-Shot Examples
[EXAMPLES]

## Error Instance to Classify
Error Code: [ERROR_CODE]
Error Message: [ERROR_MESSAGE]
Stack Trace / Context: [ERROR_CONTEXT]
Service: [SERVICE_NAME]

## Output Schema
Return a valid JSON object with the following structure:
{
  "primary_classification": {
    "category": "string",
    "confidence": 0.0-1.0,
    "rationale": "string"
  },
  "alternative_classifications": [
    {
      "category": "string",
      "confidence": 0.0-1.0,
      "rationale": "string"
    }
  ],
  "is_ambiguous": true/false,
  "ambiguity_note": "string or null"
}

## Constraints
- Only use categories from the provided taxonomy.
- If confidence is below 0.7, you MUST provide at least one alternative classification.
- The rationale must reference specific details from the error instance (e.g., error code, message text, stack trace).
- Do not invent categories or make assumptions about the system not present in the input.

To adapt this template, replace the square-bracket placeholders with live data. [TAXONOMY] should be a structured list of your error categories, such as 'Network Timeout', 'Invalid Input', 'Dependency Failure', or 'Internal Server Error'. [EXAMPLES] should contain 3-5 few-shot examples showing an error instance and its correct JSON classification. This is critical for teaching the model the boundaries of your taxonomy. The remaining placeholders ([ERROR_CODE], [ERROR_MESSAGE], etc.) should be populated from your error reporting system for each classification call. For high-stakes environments, consider adding a [RISK_LEVEL] constraint that forces a human review flag for low-confidence or ambiguous classifications.

After pasting this prompt into your orchestration layer, you must implement a validation step. The model's JSON output should be parsed and validated against the expected schema. Any output that fails to parse or is missing required fields should trigger a retry or fallback logic. For ambiguous cases where is_ambiguous is true, route the error instance to a human review queue. This ensures that your runbooks and dashboards are fed with high-confidence data, while edge cases are handled with the necessary human judgment.

This prompt is designed to be a single step within a larger error processing pipeline, not a standalone chatbot. The implementation harness must treat the model call as a deterministic classifier with a structured output contract. The primary integration point is an event-driven function that receives a batch of error instances, enriches them with relevant context (stack traces, timestamps, service names), and calls the LLM to produce a normalized classification payload. The harness is responsible for enforcing the [OUTPUT_SCHEMA], handling model refusals or malformed JSON, and routing low-confidence classifications to a human review queue.

Start by wrapping the prompt in a function that accepts a list of error objects and returns a list of classification results. Before calling the model, validate that each error object contains the required fields: error_code, error_message, and service_name. Strip any sensitive data (PII, secrets, internal IPs) using a redaction step before the prompt is assembled. Use a model with strong JSON mode support (e.g., GPT-4o, Claude 3.5 Sonnet) and set response_format to json_schema with the exact classification schema. Implement a retry loop with exponential backoff (max 3 attempts) that catches json.JSONDecodeError and schema validation failures. On the second retry, append the validation error to the prompt as additional context: "The previous output failed validation: [ERROR]. Please correct the JSON." If all retries fail, log the raw output and route the error instance to a dead-letter queue for manual triage.

For production observability, log every classification call with: the model version, prompt template hash, input error code, output root cause category, confidence score, and latency. Use these logs to build a dashboard that tracks classification consistency over time. Run a weekly eval job that samples 100 classified errors and has a senior engineer review them against a golden dataset. If agreement drops below 90%, trigger a prompt review cycle. The most common failure mode is ambiguous errors that span multiple categories—the harness should flag any classification with a confidence score below 0.7 for human review. Do not auto-close incidents based solely on LLM classifications without a human-in-the-loop checkpoint for high-severity errors.