AI Incident Postmortem Template for LLM and RAG Teams

Most incident reviews fail for the same reason: they explain what happened, but not enough about why this system failed this way and what specifically will stop it from happening again.

LLM and RAG incidents need a stricter postmortem than a normal app outage. You are usually dealing with probabilistic behavior, multiple model or prompt versions, retrieval and context construction layers, and failure modes that only show up in one cohort or one document class.

This template is designed to keep the review mechanical: collect evidence, classify the failure, isolate the affected layer, and turn the incident into a short list of measurable fixes.

Part of the Reliability hub. Related guides: Reliability Audit, AI Observability, RAG Wrong Answers Triage.

Why AI incidents need a different postmortem

In a traditional service outage, the failure path is often obvious: a dependency failed, the queue backed up, or a deploy introduced a regression. In AI systems, the failure path can span retrieval, reranking, prompt assembly, generation, tool execution, validation, and serving.

• The answer can be wrong while the request still returns HTTP 200.
• The best document can be present in retrieval but never reach the final context.
• A model change can look harmless overall but break one high-value cohort.
• Latency can explode because of reranking, retries, or tool loops instead of the model itself.
• Cost spikes can come from hidden fallback behavior, not traffic growth.

The postmortem has to prove which layer failed first, which layers amplified the issue, and which measurement would have caught it earlier.

The postmortem template

Use this as the minimum document structure. Keep it short, specific, and evidence-backed.

The best review documents also include a short evidence appendix so a future engineer can reproduce the problem without asking around in Slack.

Incident title:
Date:
Severity:
Owner:

Summary:
- What happened:
- Who was affected:
- How long it lasted:

Impact:
- User-visible impact:
- Cohorts affected:
- Business impact:

Timeline:
- Detection:
- Mitigation:
- Recovery:
- Follow-up:

Root cause:
- First failing layer:
- Why it failed:
- Why it was not caught earlier:

Contributing factors:
- Version drift:
- Retrieval or context issue:
- Tooling or serving issue:
- Monitoring gap:

Actions:
- Immediate containment:
- Prevent recurrence:
- Validation or regression gate:
- Owner:
- Due date:
- Success metric:

What evidence to attach for LLM and RAG incidents

The incident document should not depend on memory. Attach the minimum evidence needed to classify the failure.

• request ID, trace ID, and timestamp range
• user cohort, tenant, locale, intent, or workflow label
• prompt version, model version, and feature-flag state
• retrieved document IDs, chunk IDs, and reranker scores
• selected context window or final prompt snapshot
• tool-call names, arguments, retries, and outcomes
• latency by stage, not only end-to-end latency
• token counts by stage and total cost for the incident window
• validation results, refusal outcome, and fallback behavior
• before/after comparison for the same request class if available

A filled example: wrong answer, stale retrieval, and a slow reranker

Example incident: a support copilot answered with an outdated policy after a knowledge base update. The model was blamed first, but the actual failure chain was: the new documents were partially reindexed, the candidate set still included stale chunks, and reranking latency pushed the system into a fallback path for one cohort.

That is the level of specificity you want. The document should let a second engineer answer: what broke, what changed, what we verified, and what we will watch next.

How to write action items that actually close the loop

Action items should be fewer than the number of hypotheses. If you have seven possible explanations, you probably have not finished the investigation.

1. Keep each action item small enough to finish in one release cycle.
2. Assign one owner and one due date.
3. Attach a success metric or verification step.
4. Prefer prevention over cleanup, but keep immediate containment explicit.
5. Separate fixes that reduce recurrence from fixes that improve observability.

Examples of good action items:

• Add a reindex-complete check before new chunks can serve traffic.
• Segment alerts by tenant and workflow so this cohort cannot hide in a global average.
• Introduce a regression gate for the affected intent class in CI.
• Track fallback-path usage separately from the happy path.

Examples of weak action items:

• Improve monitoring.
• Look into retrieval.
• Review prompt quality.
• Make the system better.

Common mistakes

• Blaming the model too early: many failures are retrieval, freshness, or serving problems.
• Leaving out versions: if prompt, model, and index versions are missing, root cause is hard to prove.
• Using only averages: cohort-specific failures disappear in global metrics.
• Writing too many action items: the document turns into a backlog instead of a recovery plan.
• Ignoring cost and latency: AI incidents often hurt more than correctness alone.
• Skipping verification: if you do not replay the incident or compare before/after, recurrence risk stays high.

Next steps

If you already have the template but keep seeing the same class of incident, the issue is probably not documentation. It is missing control points: evaluation, tracing, freshness checks, release gates, or ownership.