Incident Timeline Reconstruction Prompt from Traces

This prompt is for incident commanders and AI SREs who need to convert a raw, timestamp-ordered set of production traces into a human-readable incident narrative. Use it during postmortem construction or stakeholder handoff when you must explain what failed first, how the failure propagated, which components were affected, and when recovery occurred. The primary job-to-be-done is transforming machine-generated span data into a coherent, evidence-backed story that engineering leads, product managers, and executives can understand without reading raw traces.

The prompt requires pre-sorted trace data with span-level detail and expects the model to ground every timeline entry in specific trace IDs and span timestamps. The input must be a complete, closed dataset from a defined incident window—do not use this prompt during active incident triage when traces are still arriving. It is designed for retrospective reconstruction after the incident window is closed and all relevant traces have been collected. The ideal user has access to an observability backend, has already isolated the traces relevant to the incident, and needs a structured output that can be pasted into a postmortem document or incident review ticket.

Do not use this prompt when traces are incomplete, when the incident is still unfolding, or when you need real-time alerting rather than a narrative. It is not a substitute for an anomaly detection system or a live dashboard. If your traces lack span-level timestamps or trace IDs, the output will be vague and ungrounded, violating the core requirement that every timeline entry be trace-backed. For ambiguous failure modes where infrastructure, model, and prompt causes are intertwined, run the Infrastructure vs. Model Failure Classification Prompt first to categorize each trace before attempting timeline reconstruction. The next step after reading this section is to prepare your trace dataset, ensure it is sorted by timestamp, and review the prompt template for required placeholders.

This section provides a copy-ready prompt template you can paste directly into your observability harness, postmortem tool, or AI orchestration layer. The template is designed to ingest a chronologically ordered set of production traces and produce a structured, human-readable incident narrative. Each output entry is backed by trace evidence, making the timeline suitable for stakeholder handoff, postmortem documentation, and compliance review. The template uses square-bracket placeholders exclusively—replace each one with actual trace data, constraints, and output format requirements before execution.

textCopy
You are an incident timeline reconstruction specialist. Your task is to analyze a set of production traces ordered by timestamp and produce a structured incident narrative. For every event in the timeline, you must cite the specific trace ID, span ID, or log line that supports it. Do not infer events without trace evidence. If evidence is ambiguous, flag it as uncertain.

[TRACES]
<!-- Insert chronologically ordered trace data here. Each trace should include: trace_id, timestamp, service, operation, status, error_message (if any), latency_ms, and any relevant span or log details. -->
[/TRACES]

[CONSTRAINTS]
<!-- Specify any constraints such as: maximum timeline entries, required sections, severity thresholds, or components to focus on. -->
[/CONSTRAINTS]

[OUTPUT_SCHEMA]
<!-- Define the exact output structure. Example:
{
  "incident_id": "string",
  "generated_at": "ISO8601 timestamp",
  "timeline": [
    {
      "timestamp": "ISO8601",
      "event_type": "failure|propagation|recovery|annotation",
      "component": "string",
      "description": "string",
      "trace_evidence": ["trace_id:span_id"],
      "confidence": "high|medium|low",
      "impact": "string"
    }
  ],
  "summary": "string",
  "open_questions": ["string"]
}
-->
[/OUTPUT_SCHEMA]

[RISK_LEVEL]
<!-- Specify the risk context: low, medium, high, critical. High or critical risk levels should trigger additional human review flags in the output. -->
[/RISK_LEVEL]

[HUMAN_REVIEW_FLAG]
<!-- Set to true if the output must include explicit markers for entries that require human verification before stakeholder distribution. -->
[/HUMAN_REVIEW_FLAG]

Instructions:
1. Parse all traces and order them by timestamp.
2. Identify the initial failure event—the first trace indicating an anomaly, error, or threshold breach.
3. Trace the propagation path: which components were affected, in what order, and with what latency.
4. Identify recovery markers: the first trace indicating service restoration, failover completion, or error rate normalization.
5. For each timeline entry, include at least one trace_evidence reference.
6. If multiple traces corroborate an event, include the strongest evidence.
7. Flag any gaps in the trace data where the timeline is incomplete.
8. If [RISK_LEVEL] is high or critical, or [HUMAN_REVIEW_FLAG] is true, append a "requires_human_review" boolean to each timeline entry and set it to true for any entry with low confidence or ambiguous evidence.
9. Output ONLY valid JSON conforming to [OUTPUT_SCHEMA]. Do not include commentary outside the JSON.

To adapt this template, replace each bracketed section with production data and configuration. The [TRACES] block should contain the raw trace data—this can be JSON, structured logs, or a formatted table, but consistency across traces is critical for reliable reconstruction. The [OUTPUT_SCHEMA] block defines the exact JSON structure your downstream tooling expects; modify it to match your postmortem system's schema. The [CONSTRAINTS] block lets you scope the analysis to specific components, time windows, or severity levels. Set [RISK_LEVEL] and [HUMAN_REVIEW_FLAG] based on your incident response policy—for customer-facing outages or regulated systems, always require human review of low-confidence entries before the timeline is shared externally. After pasting, validate that the model's output conforms to your schema using a JSON validator before ingestion into your postmortem tool. If the model produces malformed JSON or entries without trace evidence, use a retry prompt with stricter instructions or escalate to a human responder.

This prompt is designed to be invoked as part of a post-incident automation pipeline, not as a one-off chat interaction. The primary integration point is your observability platform's API or a batch processing script that collects trace spans from your tracing backend (e.g., Datadog, Honeycomb, OpenTelemetry collector) and feeds them into the prompt. The input must be a chronologically ordered array of trace objects, each containing at minimum a timestamp, span_id, service, operation, status_code, and any associated error_message or metadata fields. Before calling the LLM, validate that the trace list is non-empty, sorted ascending by timestamp, and contains no duplicate span IDs. A pre-processing step should also truncate or summarize excessively large metadata blobs to avoid context-window overflow, keeping the total input under roughly 60% of the model's context limit to leave room for the output timeline.

The implementation should follow a validate → generate → validate → escalate pattern. After the model returns the structured timeline JSON, run a post-generation validator that checks: (1) every timeline entry has a non-null timestamp and evidence_trace_ids array, (2) each referenced trace ID exists in the input set, (3) the timeline is still sorted chronologically, and (4) the propagation_path field forms a connected graph (no orphaned services unless marked as the initial failure). If validation fails, retry once with the validation errors appended to the prompt as [CONSTRAINTS] feedback. If the second attempt also fails, escalate to a human incident commander with the raw traces and the partial timeline for manual reconstruction. Log every attempt—including input trace count, output timeline length, validation pass/fail, and retry count—to your incident management channel for auditability.

Model choice matters here. Use a model with strong structured output capabilities and a large context window (e.g., Claude 3.5 Sonnet or GPT-4o with structured outputs enabled). Set temperature=0 or near-zero to maximize factual consistency across trace evidence. If your traces contain sensitive data, run the prompt in a private deployment or use a redaction proxy to strip PII, secrets, and internal hostnames before the data reaches the model. For high-severity incidents, always require a human reviewer to approve the final timeline before it is shared with stakeholders or attached to the postmortem document. The prompt's [RISK_LEVEL] parameter should be set to high for any incident involving data loss, security impact, or customer-facing downtime, which triggers the mandatory human-approval gate in your workflow.