Agent Root Cause Analysis Audit Prompt

This prompt is for incident responders, SRE teams, and governance engineers who need to reconstruct why a multi-agent workflow failed. It takes raw execution artifacts—agent decision logs, tool call traces, error outputs, state snapshots, and handoff records—and produces a structured, blameless root cause analysis report. The ideal user is someone who already has access to the full execution trace but cannot attribute the failure to a single component by inspection alone. The prompt forces systematic reasoning across agent boundaries, tool interactions, and state transitions that human reviewers often overlook when scanning logs manually.

Use this prompt when a production incident involves two or more agents and the failure mode is non-obvious: a task was dropped during handoff, an agent acted on stale context, a tool returned an unexpected error that cascaded, or an arbitration decision produced an incorrect final answer. The prompt is designed for post-incident analysis, not real-time alerting or live debugging. You must provide complete artifacts as input—partial logs or redacted traces will produce unreliable conclusions. The prompt includes built-in checks against premature conclusions, ignored contributing factors, and misattribution of blame to a single agent when the root cause is systemic.

Do not use this prompt for single-agent debugging, real-time monitoring, or incidents where the failure is already understood. It is not a replacement for structured logging or observability tooling; it is a reasoning aid that complements your existing incident response process. Before running this prompt, ensure you have collected all relevant artifacts and that sensitive data has been redacted according to your organization's policies. The output should be reviewed by a human incident commander before being shared with stakeholders or attached to a postmortem document.

This prompt is the core instruction set you will send to an LLM to perform a structured root cause analysis on a failed multi-agent workflow. It is designed to be pasted directly into your model's context window. Before execution, you must replace every square-bracket placeholder with real data from your incident. The prompt forces the model to act as an impartial investigator, synthesizing raw telemetry—logs, error traces, and state snapshots—into a blameless report that prioritizes systemic fixes over individual fault.

markdownCopy
You are an impartial incident investigator analyzing a failed multi-agent workflow. Your goal is to produce a blameless root cause analysis report based strictly on the provided evidence. Do not speculate beyond the provided data. If the evidence is insufficient to determine a root cause, state that explicitly.

## INPUT DATA
- **Workflow Logs:** [WORKFLOW_LOGS]
- **Error Traces:** [ERROR_TRACES]
- **Agent State Snapshots:** [STATE_SNAPSHOTS]
- **Expected Workflow Definition:** [WORKFLOW_DEFINITION]

## ANALYSIS CONSTRAINTS
- **Blameless Posture:** Focus on systemic failures, process gaps, and technical triggers. Do not assign blame to individuals or teams.
- **Evidence Grounding:** Every causal claim must be supported by a direct quote or timestamped reference from the INPUT DATA.
- **Premature Conclusion Check:** Before finalizing, explicitly list any alternative hypotheses that were considered and why they were ruled out based on the evidence.
- **Contributing Factors:** Identify all contributing factors, not just the initial trigger. Classify each as a trigger, amplifier, or latent condition.

## OUTPUT SCHEMA
Respond with a JSON object conforming to this structure:
{
  "incident_summary": "A concise, one-paragraph summary of what happened.",
  "timeline": [
    {
      "timestamp": "ISO 8601 timestamp",
      "agent": "Agent identifier",
      "event": "Description of the event",
      "evidence_ref": "Direct quote or log line from INPUT DATA"
    }
  ],
  "root_cause_analysis": {
    "primary_trigger": "The initial event that started the failure chain.",
    "contributing_factors": [
      {
        "type": "trigger | amplifier | latent_condition",
        "description": "Description of the factor.",
        "evidence_ref": "Supporting evidence from INPUT DATA"
      }
    ],
    "ruled_out_hypotheses": [
      {
        "hypothesis": "A potential cause that was investigated and rejected.",
        "reason_for_rejection": "Why the evidence does not support this hypothesis."
      }
    ]
  },
  "systemic_recommendations": [
    {
      "category": "handoff_protocol | state_management | error_handling | tool_contract | observability | other",
      "recommendation": "Actionable recommendation to prevent recurrence.",
      "addressed_factors": ["List of contributing factors this recommendation addresses"]
    }
  ],
  "evidence_gaps": ["List of questions that cannot be answered with the provided data."]
}

To adapt this template, start by mapping your internal data sources to the placeholders. [WORKFLOW_LOGS] should contain the raw, chronological execution logs from your agent orchestration framework. [ERROR_TRACES] must include full stack traces and error codes, not just the final exception message. [STATE_SNAPSHOTS] are critical for diagnosing handoff failures; provide the input and output payloads for each agent. [WORKFLOW_DEFINITION] is the expected execution graph or SOP, which serves as the baseline for detecting deviations. If your system does not capture one of these data types, replace the placeholder with a statement like NO STATE SNAPSHOTS AVAILABLE to prevent the model from hallucinating missing data.

Before integrating this prompt into an automated incident response pipeline, you must build a validation layer around it. The model's JSON output must be checked for schema compliance, and every evidence_ref field should be programmatically verified as a substring match within the original INPUT DATA to prevent hallucinated citations. For high-severity incidents, the generated report should be treated as a draft and routed to a human responder for review and approval before being published to a postmortem register. Never use this prompt to make automated decisions about system rollback or agent permission changes without human-in-the-loop confirmation.

The Agent Root Cause Analysis Audit Prompt is designed to be a critical node in a post-incident review pipeline, not a standalone chat interaction. It should be invoked automatically when a multi-agent workflow terminates with an error status, exceeds a latency threshold, or is flagged by a human operator. The harness must assemble the required inputs—agent decision logs, tool call traces, error stacks, state snapshots, and the original user request—into a single structured context block before calling the model. Because the output is a formal RCA report, the implementation must treat this prompt as a governed artifact generator: the report should be versioned, stored immutably, and linked to the incident ticket before any human reviews it.

Wire the prompt into your incident management system (e.g., PagerDuty, ServiceNow, or a custom orchestrator) using a webhook or event-driven function. The function should: (1) collect all relevant artifacts from your agent observability store, (2) validate that required inputs are present and non-empty—reject the run if agent logs are missing or truncated, (3) assemble the prompt with the [INCIDENT_TIMELINE], [AGENT_LOGS], [ERROR_TRACES], and [STATE_SNAPSHOTS] placeholders populated, (4) call a capable reasoning model (Claude 3.5 Sonnet or GPT-4o are appropriate for the analytical depth required), and (5) parse the output against a strict JSON schema that includes fields for root_cause, contributing_factors, timeline_of_failure, premature_conclusions_avoided, and recommendations. If parsing fails, retry once with a repair prompt that includes the schema and the raw output. After two failures, escalate to a human with the raw model response attached.

Before the RCA report is accepted, run a set of automated evals. At minimum, check that the root_cause field is not empty, that contributing_factors includes at least one factor beyond the immediate error, and that the premature_conclusions_avoided section explicitly lists hypotheses the model considered and rejected with reasoning. Use a second LLM judge prompt to verify that every factual claim in the report is grounded in the provided logs—flag any hallucinated event timestamps, agent names, or tool calls. Store the eval results alongside the report. For high-severity incidents, route the report to a human incident commander for approval before it is published to the incident timeline. Never allow the model to directly close an incident ticket or trigger a rollback without human confirmation. The harness should log the full prompt, response, and eval results to your audit store for future governance reviews.