Root-Cause Isolation Decision Prompt

This prompt is for incident responders and AI SREs who need to classify the failure domain of a single production trace before escalating or applying a fix. The job-to-be-done is rapid, evidence-based triage: given a structured trace containing user input, retrieval steps, tool calls, model outputs, and metadata, the prompt must output a classified root cause (e.g., prompt defect, model behavior change, retrieval gap, tool failure, or infrastructure error) with a confidence score and supporting evidence. The ideal user is an engineer on-call who has pulled a single anomalous trace from observability tools and needs a structured diagnosis to decide whether to roll back a prompt, investigate a model update, check a vector database, or page the infrastructure team.

This prompt is designed for isolated trace analysis, not aggregate pattern detection. Use it when you have a single trace that represents a known failure—such as a hallucinated answer, a refused request, a tool-call loop, or a latency spike—and you need to narrow the cause to one domain before correlating across sessions. The prompt requires a well-formed trace input that includes at minimum: the user query, the system prompt version, retrieved context with scores, tool-call sequences with arguments and responses, the final model output, and any error codes or latency measurements. Without this structured evidence, the prompt cannot produce a reliable classification. Do not use this prompt for real-time streaming decisions, for classifying user intent, or for evaluating model quality in aggregate; it is a diagnostic tool for post-hoc incident response, not a routing or scoring prompt.

The output is a structured root-cause classification with a confidence level and a harness for validating against known incident labels. This means you should have a set of labeled historical incidents or synthetic failure traces to test the prompt before relying on it in production. The classification must be falsifiable: if the prompt labels a trace as a retrieval gap, you should be able to confirm by inspecting the retrieved chunks and ranking scores. If it labels a trace as a model behavior change, you should be able to replay the same input against a previous model version. Before shipping this prompt into your incident response runbook, run it against at least 20 labeled traces covering all five failure domains and measure precision and recall per class. If the prompt cannot reach 80% agreement with human-labeled root causes on your data, add more trace evidence fields or constrain the output to fewer classes with higher confidence thresholds. In high-severity incidents, always require human review of the classification before taking automated action such as rolling back a prompt or blocking a model version.

This section provides a copy-ready prompt template for the Root-Cause Isolation Decision Prompt. The template is designed to be dropped into your observability tooling, incident response runbook, or an automated trace analysis pipeline. It accepts a structured trace object and a set of known failure domains, then outputs a classified root cause with a confidence score and supporting evidence. The template uses square-bracket placeholders for all dynamic inputs, making it safe to template in code, CI/CD pipelines, or a prompt management platform. Before using this prompt in production, ensure your trace data is sanitized of any PII or secrets, and confirm that the failure domain taxonomy matches your system's actual failure modes.

textCopy
You are an AI SRE analyzing a single production trace to classify the root-cause failure domain. Your analysis must be evidence-based, conservative, and traceable to specific trace events.

## INPUTS

### Trace Data
```json
[TRACE_JSON]

Failure Domain Taxonomy

[FAILURE_DOMAINS]

Known Incident Labels (for calibration)

[INCIDENT_LABELS]

TASK

1. Parse the trace data and reconstruct the chronological sequence of events: user input, retrieval steps, tool calls, model inferences, and final output.
2. For each event, flag any anomalies, errors, timeouts, malformed arguments, missing context, or unexpected behavior.
3. Map the observed anomalies to the most likely failure domain from the provided taxonomy.
4. If multiple domains are plausible, rank them by likelihood and explain the differential diagnosis.
5. Assign a confidence score (0.0 to 1.0) to your primary classification.
6. Cite specific trace spans, log lines, or event timestamps as evidence for your conclusion.

CONSTRAINTS

• Do not speculate beyond the evidence present in the trace.
• If the trace is incomplete or missing critical spans, flag this as a limiting factor and reduce confidence accordingly.
• Do not output PII, secrets, or sensitive data in your explanation. Reference span IDs instead.
• If the root cause is ambiguous, explicitly state what additional data would resolve the ambiguity.
• Prefer the most specific failure domain available. Avoid defaulting to "model behavior change" unless tool, retrieval, and infrastructure causes are ruled out.

OUTPUT SCHEMA

Return a valid JSON object with this exact structure:

jsonCopy
{
  "trace_id": "string",
  "primary_root_cause": {
    "domain": "string (from taxonomy)",
    "confidence": 0.0,
    "evidence_spans": ["span_id_1", "span_id_2"],
    "rationale": "string explaining why this domain is the best fit"
  },
  "differential_diagnosis": [
    {
      "domain": "string",
      "confidence": 0.0,
      "rationale": "string explaining why this domain is less likely"
    }
  ],
  "anomalies_flagged": [
    {
      "span_id": "string",
      "anomaly_type": "string (e.g., timeout, malformed_args, missing_context, empty_retrieval, refusal, format_drift)",
      "description": "string"
    }
  ],
  "trace_completeness": {
    "status": "complete | partial | minimal",
    "missing_spans": ["string"],
    "impact_on_confidence": "string"
  },
  "recommended_actions": ["string"]
}

EXAMPLES

[FEW_SHOT_EXAMPLES]

RISK LEVEL

[RISK_LEVEL]

To adapt this template for your environment, replace each square-bracket placeholder with concrete data. [TRACE_JSON] should contain the full trace object from your observability platform, including spans, events, and metadata. [FAILURE_DOMAINS] should list the failure categories your team recognizes—such as prompt_defect, model_behavior_change, retrieval_gap, tool_failure, infrastructure_error, context_window_overflow, or routing_error. [INCIDENT_LABELS] is optional but recommended for calibration; it provides previously confirmed root-cause labels that help the model align its classification with your team's historical decisions. [FEW_SHOT_EXAMPLES] should include 2–3 annotated traces showing correct classifications, especially edge cases where the root cause was non-obvious. [RISK_LEVEL] should be set to high, medium, or low based on the blast radius of the system under review. For high-risk systems, route all classifications with confidence below 0.85 to a human reviewer before taking automated remediation actions. Validate the model's output against your incident labels quarterly to detect classification drift, and log every classification decision with the trace ID, confidence score, and reviewing human (if applicable) for auditability.

This prompt is designed to be called programmatically as part of an automated incident triage step or a manual SRE investigation workflow. The primary input is a structured trace object containing spans for user input, retrieval, tool calls, model outputs, and metadata. Before calling the model, your application harness must validate that the trace payload conforms to the expected schema—missing spans or malformed timestamps will degrade classification accuracy. The prompt expects a complete trace, not a summary, because root-cause isolation depends on inspecting the sequence and content of events, not just the final output.

In a production harness, you should wrap the model call in a retry layer with exponential backoff for transient API failures, but do not retry on validation failures. After receiving the model's JSON output, validate it against a strict schema that checks for the required fields: root_cause_category, confidence_score, evidence_summary, and alternative_hypotheses. If the output fails schema validation, log the raw response and fall back to a human review queue rather than silently accepting a malformed classification. For high-severity incidents, always route the classified output to a human responder for confirmation before triggering automated remediation. Store the classified root cause alongside the trace ID in your observability platform to build a labeled dataset for future model evaluation and fine-tuning.

Choose a model with strong structured output capabilities and a context window large enough to hold your longest traces plus the prompt instructions. If traces routinely exceed the model's context limit, implement a pre-processing step that summarizes or truncates low-signal spans (e.g., verbose debug logs) before passing the trace to the prompt. Avoid using this prompt on streaming or incomplete traces; the classification accuracy drops sharply when the model cannot see the full session. For teams running continuous monitoring, batch-process closed traces on a slight delay rather than attempting real-time classification, which adds latency pressure without improving incident response time.