How to Write an Engineering Incident Report That Actually Gets Read

The Slack channel has finally gone quiet. The alerts have stopped firing. The database is stable, the rollback is complete, and the immediate panic of the last three hours has subsided into a dull, caffeine-fueled exhaustion.

You are the engineering lead. You fixed the system.

Now, you have to explain what happened.

You open a blank document and stare at the blinking cursor. You know exactly what went wrong — a rogue database query locked a table, causing a cascading failure across the payment processing service. But how do you explain that to the VP of Product, the Head of Support, and the CEO without sounding defensive, overly technical, or hopelessly vague?

Most incident reports fail because they optimize for the wrong audience. They are written as a defensive maneuver. They read like a play-by-play of every Slack message, designed to prove that the engineers were working hard and trying their best. The result is a document that is too long to be read and too thin to be useful.

Leadership does not need a detective novel. They need clarity on impact, root cause, and what is changing.

If you have been asked to formalize your incident response process, or if your current reports are either too thin to be useful or too long to be read, you need a different approach. Here is how to write a report that actually serves its purpose.

What Goes in the Report (and What Stays Out)

The incident report is a communication artifact. It is not the postmortem.

The engineering postmortem is a learning artifact for the team that has to prevent the recurrence. It is analytical, introspective, and written after investigators have had time to explore logs, code changes, and human decision paths — a distinction COEhub articulates well in their 2025 guide on the subject. The incident report is for leadership and cross-functional stakeholders who need to make resourcing decisions and communicate with customers. They have different needs. Leadership needs enough detail to understand the business risk. They do not need to understand the exact syntax of the failing query.

Your report needs four things.

The first is an executive summary. This is the impact scope, the timeline, and the resolution status. Leadership should be able to read this block and stop. If they want more, the rest of the document is there. But the executive summary should be self-contained.

The second is the timeline. Key events only. What broke, when it was detected, when it was contained, when it was resolved. The Google SRE Book describes a postmortem as "a written record of an incident, its impact, the actions taken to mitigate or resolve it, the root cause(s), and the follow-up actions to prevent the incident from recurring." The timeline is the spine of that record. It should be a story that hits the key moments and turning points, not an audit trail of every command run in the terminal.

The third is the root cause. This is the actual technical failure. Not "human error." Not "communication breakdown." If the root cause is a missing safeguard, name the safeguard. If the root cause is a configuration change that was not load-tested, say that. Stopping at "someone deployed bad code" is not a root cause analysis — it is a description of a symptom.

The fourth is the prevention plan. Concrete next actions with owners and dates. If nothing is changing, the report is not done.

What stays out? Blame language. "The database administrator failed to check the index" is blame. "The system did not require an index check before deployment" is a systemic observation. The distinction matters. Research on blameless postmortem culture, pioneered at companies like Etsy, shows that blame-oriented reports create a cycle where engineers become reluctant to share the details necessary to understand how a failure actually happened. When people are afraid of being named in the report, they stop giving you the information you need to prevent the next one.

Leave out anything that happened after the incident was contained, unless it is directly relevant to prevention. Leave out implementation details that do not affect the narrative. The report is not the bug ticket.

The Timeline Is Not a Detective Novel

When you are in the middle of an incident, every minute feels crucial. When you are writing the report, most of those minutes do not matter.

The timeline should not be a dump of your incident channel. It should mark the major state changes of the system: detected, mitigated, resolved. Include timestamps. Be precise about when things happened, but be ruthless about cutting the noise. The incident.io guide describes the ideal timeline as "less of an audit trail, and more of a story that hits the key moments and turning points as the incident played out." That is the right framing. You are not writing a legal transcript. You are writing a narrative that helps someone who was not in the room understand the shape of the failure.

Use past tense and active voice throughout. "The cache layer failed" is cleaner than "there was a cache layer failure." The passive construction distances the reader from what actually happened.

Quantify the impact wherever possible. "Approximately 1,200 users experienced checkout failures between 14:03 and 16:47 UTC" is a sentence leadership can act on. "Many users had trouble" is not. The Google SRE Workbook makes this point explicitly: a well-informed estimate is better than no data at all, because if you cannot measure the impact, you cannot know the incident is truly resolved.

If you do not know something yet, say so explicitly and commit to a follow-up date. Uncertainty is not a weakness in a report. Unexplained gaps are.

Naming the Actual Failure

Root cause analysis is difficult because it is tempting to stop at the first human action. Someone deployed bad code. That is what happened. But why was bad code allowed to be deployed?

The PagerDuty blameless postmortem guide draws on Sidney Dekker's work on human error to make a useful distinction: the "old view" of human error treats people as the cause of failure and focuses on finding the bad actor. The "new view" treats human error as a symptom of systemic vulnerabilities deeper inside the organization. The old view produces reports that name people. The new view produces reports that name missing safeguards.

If the root cause is a missing safeguard, name the safeguard. "The deployment pipeline did not require a load test before pushing to production" is a root cause. "The engineer did not run a load test" is blame.

Research analyzing publicly available incident reports from companies including GitHub, Cloudflare, Slack, and Epic Games found that failures frequently cascade through systems in ways that are not obvious from any single human action. The root cause is almost never the last person who touched the system. It is the condition that allowed a reasonable action to produce an unreasonable outcome.

Cloudflare's 2023 incident report on their control plane outage is a good example of this done right. The report named specific architectural dependencies that had not been tested, specific decisions about high-availability clusters that turned out to be incomplete, and specific organizational practices around new product onboarding that allowed technical debt to accumulate. No individual was named. The systemic conditions were named.

A separate study of software engineering practices at high-reliability organizations — including a national space research center — found that even in environments with strict safety constraints, structured processes for learning from failures are often informal and ad hoc, and that systemic barriers like documentation gaps and team turnover allow recurring failures to persist despite general process adherence. The implication is that a good incident report is not just a communication artifact. It is institutional memory. If it is written well, it outlasts the people who were in the room.

The Part Everyone Gets Wrong About Prevention

The most critical section of the report is the prevention plan. This is where the cost of the failure gets converted into education.

If your preventive measure is "be more careful next time," you have not prevented anything. As the Google SRE Workbook puts it, trying to change human behavior is less reliable than changing automated systems and processes. One of the most common failure modes in postmortem action items is vague language. "Improve monitoring" and "make the process better" are not action items. They are aspirations.

Concrete next actions need owners and dates. What are we building? What are we changing? Who is responsible for it, and when will it be done?

Research on post-incident action items found that actions without clear owners are significantly less likely to be resolved. The accountability structure of the prevention plan is not bureaucracy. It is the mechanism by which the report actually produces change.

If the root cause was a lack of visibility, the action item is to instrument the specific service. If the root cause was a manual step in a deployment, the action item is to automate that step. If the root cause was a missing rate limit, the action item is to add the rate limit. The Pragmatic Engineer's analysis of incident handling practices across more than 50 engineering teams found that the most effective organizations treat incident action items as first-class work, tracked with the same rigor as product features. Teams that let action items drift into a backlog and never get prioritized tend to see the same classes of incidents recur.

A Template You Can Actually Use

The full incident report template looks like this:

The executive summary should contain enough information that a non-technical stakeholder can read it and understand the business impact without reading the rest of the document. The timeline should be readable in under two minutes. The root cause should be two sentences. The prevention plan should have names and dates.

One thing worth being explicit about: the incident report and the engineering postmortem are not the same document, and they should not be written as one. The incident report is for leadership, cross-functional stakeholders, and sometimes customers. The postmortem is for the engineering team. Conflating them produces a document that is too technical for leadership and too high-level for the engineers who need to actually learn from it. Write both. Keep them separate.

Where Doc Holiday Fits

The hardest part of writing an incident report shouldn't be remembering when the database spiked. It should be the analysis.

Many engineering teams now generate skeletal incident reports directly from their monitoring and ticketing systems. Doc Holiday can pull structured data from Jira, PagerDuty, Slack threads, and deployment logs to auto-generate a first draft with the timeline, affected services, and key actors already populated. The engineering lead still writes the root cause analysis and the prevention plan — the parts that actually require judgment. But the manual assembly of "what happened when" is already done.

This means the report gets written within hours, not days. And the engineer spends their time on the analysis that matters.