Tool Failure Root Cause Hypothesis Prompt

This prompt is for incident responders and platform reliability engineers who need to move from 'the tool is down' to a ranked, testable set of root cause hypotheses. It takes structured incident signals—error patterns, recent changes, dependency graphs, and environmental telemetry—and produces a differential diagnosis, not a single guess. The primary job-to-be-done is accelerating the investigation phase of a tool outage by forcing structured reasoning over multiple failure domains before the team commits to a single recovery path.

Use this prompt when you have at least three concrete signals: error codes with timestamps, a known dependency graph, a list of recent changes (deploys, config pushes, upstream provider updates), and environmental context like latency baselines or resource saturation metrics. The prompt works best when the incident is ambiguous—multiple components could be at fault, and the team needs to avoid anchoring on the first plausible cause. Do not use this prompt for simple, known failure modes with a documented runbook, or when the outage is already confirmed to be an external provider issue with no internal dependency angle. It is also inappropriate for real-time automated triage without human review; the output is a hypothesis list for an experienced responder to evaluate, not a decision to execute.

The prompt requires explicit constraints on hypothesis quality: each hypothesis must be falsifiable, include the evidence that supports it, identify confounding factors that could mislead the investigation, and suggest a specific diagnostic test. Without these constraints, the model will produce plausible-sounding but untestable narratives. Wire the output into your incident channel or runbook tool, but always require a human to mark hypotheses as 'testing,' 'confirmed,' or 'ruled out' before any remediation action. The next section provides the exact prompt template you can adapt and the harness you need to make it production-safe.

This prompt template is designed for incident responders and reliability engineers who need to move from observing tool failure symptoms to generating testable root cause hypotheses. It ingests structured error patterns, dependency graphs, recent change logs, and environmental signals, then produces a ranked list of hypotheses with supporting evidence, confounding factors, and explicit testability criteria. The template uses square-bracket placeholders so you can wire it directly into an incident response agent, a chatbot, or an internal diagnostics tool without rewriting the core reasoning structure.

textCopy
You are an incident diagnostics assistant specializing in distributed systems and tool dependency failures. Your task is to analyze the provided failure signals and produce a ranked list of root cause hypotheses.

## INPUT

### Error Patterns
[ERROR_PATTERNS]

### Dependency Graph
[DEPENDENCY_GRAPH]

### Recent Changes
[RECENT_CHANGES]

### Environmental Signals
[ENVIRONMENTAL_SIGNALS]

### Incident Timeline (if available)
[TIMELINE]

## CONSTRAINTS
- Rank hypotheses from most likely to least likely.
- For each hypothesis, cite specific evidence from the input signals.
- Identify at least one confounding factor per hypothesis that could mislead diagnosis.
- Mark each hypothesis as testable or not testable with current observability.
- If insufficient data exists to form a hypothesis, state that explicitly rather than guessing.
- Do not fabricate metrics, logs, or events not present in the input.

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "incident_summary": "One-sentence summary of the observed failure.",
  "hypotheses": [
    {
      "rank": 1,
      "hypothesis": "Concise root cause hypothesis.",
      "supporting_evidence": ["Evidence point 1", "Evidence point 2"],
      "confounding_factors": ["Factor that could produce similar symptoms"],
      "testability": "testable | partially_testable | not_testable",
      "suggested_test": "If testable, describe a specific diagnostic action.",
      "confidence": "high | medium | low"
    }
  ],
  "data_gaps": ["What additional data would improve diagnosis."],
  "immediate_actions": ["Actions to take before full root cause confirmation."]
}

## RISK LEVEL
[RISK_LEVEL]

If RISK_LEVEL is high or critical, prefix your response with: "HUMAN REVIEW REQUIRED: This diagnosis involves high-severity systems. Escalate before acting on these hypotheses."

To adapt this template, replace each square-bracket placeholder with data from your observability stack. [ERROR_PATTERNS] should include structured error codes, status distributions, and message signatures, not raw log dumps. [DEPENDENCY_GRAPH] works best as a concise adjacency list or Mermaid diagram showing which tools call which. [RECENT_CHANGES] should be a timestamped list of deploys, config changes, and dependency updates. [ENVIRONMENTAL_SIGNALS] captures latency percentiles, resource saturation, and upstream provider status. The [RISK_LEVEL] field gates whether the model prepends a mandatory human-review warning. For production use, validate the output JSON against the schema before surfacing hypotheses to an incident commander. Run periodic eval checks with known failure scenarios to confirm the model correctly identifies confounding factors and does not over-index on the most recent change.

This prompt is designed to be called during active incident response, not as a background analysis tool. It should be wired into your incident management platform (e.g., PagerDuty, FireHydrant, or a custom Slack bot) so that an on-call responder can invoke it with a single command, passing the current error signature, a recent dependency graph snapshot, and any known environmental changes. The prompt expects structured inputs and returns ranked hypotheses, which means your harness must assemble those inputs from your observability stack before calling the model. Do not ask the responder to manually copy-paste logs into a text box; that introduces transcription errors and delays when every minute counts.

The harness should follow a strict validate → invoke → parse → present → log loop. Before calling the model, validate that all required placeholders are populated: [ERROR_PATTERNS] must contain structured error data (status codes, error bodies, timestamps), [DEPENDENCY_GRAPH] must be a recent snapshot from your service topology (not a stale diagram), [RECENT_CHANGES] must be pulled from your deployment or config change feed, and [ENVIRONMENTAL_SIGNALS] must include metrics like latency percentiles, CPU saturation, and upstream dependency health. If any input is missing or stale, the harness should refuse to invoke and prompt the responder to refresh the data source. After invocation, parse the model's JSON output against a strict schema that requires each hypothesis to include a testability_score (0.0–1.0) and a confounding_factors array. Reject and retry any response that fails schema validation. Log every invocation—inputs, raw output, parsed hypotheses, and the responder's eventual chosen root cause—to build a training corpus for fine-tuning and to enable post-incident review of the model's diagnostic accuracy.

For model choice, prefer a model with strong reasoning benchmarks and structured output support (e.g., Claude 3.5 Sonnet or GPT-4o with response_format set to json_schema). Set temperature to 0.1–0.2 to reduce variance in hypothesis ranking. Implement a retry budget of 2 attempts for schema validation failures, then escalate to a human with the raw model output and a warning that automated parsing failed. Do not present unvalidated hypotheses directly to the responder; a hallucinated root cause can send your incident response down a costly wrong path. Wire the harness output into your incident channel as a threaded message with the top 3 hypotheses, their testability scores, and a one-click button to log which hypothesis was confirmed or rejected after investigation. This closed feedback loop is essential for evaluating the prompt's real-world accuracy and for detecting drift in your dependency graph or error taxonomy over time.