Skip to content
Writing Style Library

Incident Report

A customer-facing account of a service incident: what happened, the impact, and what is being done.

Incident Report

Section titled “Incident Report”

An incident report is the external, customer-facing record of a service disruption. It is written for the people who were affected: customers, partners, and the public. Its defining job is not forensic - it is relational. The format exists to acknowledge what happened, take organizational accountability, and communicate what is being done, all in language accessible to someone who is not an engineer and who cares primarily about whether their service is reliable and trustworthy again.

An incident report is not always a post-incident document. It may be issued during an active outage as a live status update - with a Status field of Investigating or Identified - and then revised or finalized after service is restored with a complete account of the timeline, root cause, and remediation. The same structure serves both moments: an initial report early in an incident builds trust by showing the team is aware and working; the final report closes the loop with customers who deserve to know what actually happened and what has changed.

An incident report is not a postmortem. A postmortem is an internal, blameless learning document written for the engineering team: it asks why the system failed and what processes can improve. An incident report is written for customers: it states what they experienced, what caused it at an accessible level of detail, and what the organization is committing to. The distinction matters because the two audiences need fundamentally different things, and conflating the formats either exposes internal detail that customers do not need or strips the learning depth that engineers do.

Typical length: 300 to 600 words for a final report. An initial report issued while the incident is still active may be shorter, with additional sections appended as the situation develops and resolves.

Canonical template

Section titled “Canonical template”
# Incident Report: [Incident Name or ID]


## Status


[Investigating | Identified | Monitoring | Resolved] - [date and time, timezone]


## Summary


[One to two sentences: what service was affected, what customers experienced, and when.]


## Impact


- Services affected: [list]
- Customers affected: [scope or percentage, if known]
- Duration: [start time] to [end time] ([total duration])


## Timeline


- [time] - [event]
- [time] - [event]
- [time] - Incident declared resolved


## Root Cause


[Plain-language explanation of what caused the failure. Accessible to a non-engineer.
Avoid internal jargon, team names, and speculative detail.]


## Resolution


[What was done to restore service.]


## Next Steps


- [Specific, committed remediation action]
- [Expected completion or owner, if known]

When to use

Section titled “When to use”

Communicating a service disruption to affected customers during or after an incident, publishing a final account after service is restored with root cause and remediation, meeting contractual or compliance obligations to report downtime or data events, building or restoring customer trust through transparent accountable communication, responding to public or stakeholder inquiries about what happened and what has changed.

When not to use

Section titled “When not to use”

Internal engineering retrospectives on what went wrong, routine maintenance notices or scheduled updates with no unplanned service impact, internal team communication during the incident response itself.

Pairs well with

Section titled “Pairs well with”

executive, direct-communicator, candid, diplomatic, problem-solution, executive-summary

Often confused with

Section titled “Often confused with”

postmortem: A postmortem is an internal, blameless engineering retrospective - it asks why the system failed and how to improve team processes, and is written for the engineering team. An incident report is written for customers and the public: it takes organizational accountability, explains impact in accessible terms, and commits to remediation without exposing the forensic depth that belongs in the postmortem.

public-statement: An incident-report covers a technical service disruption with a reconstructable timeline and root cause (Status, Timeline, Root Cause, Resolution) and is addressed to affected users who need to know what failed and what changed. A public-statement covers a controversy or decision under scrutiny that has no incident timeline; it is carried as institutional prose with a named signatory and addresses a watching public rather than a population of technically affected customers.

Tells

Section titled “Tells”
  • A Status field at the top showing investigation stage: Investigating, Identified, Monitoring, or Resolved
  • An Impact section that names affected services and customer populations in plain language
  • A chronological Timeline of key events leading to and through the incident
  • A Root Cause section written for a non-engineer: category of failure, not internal system detail
  • A Next Steps or Remediation section with specific, committed actions rather than vague assurances
  • Organizational accountability taken without naming individuals or exposing internal team structure
  • Tone that is direct and factual with a single, clear acknowledgment of customer impact

Anti-patterns

Section titled “Anti-patterns”
  • Using internal jargon, system names, or engineering architecture detail in the root cause section - Customer-facing reports must be accessible to affected users; unexplained technical language shifts the burden of interpretation onto the reader and signals the writer has not translated the incident for its actual audience.
  • Omitting the customer impact and leading with the technical timeline - Customers need to understand what they experienced before they can care about the internal sequence of events; opening with a timeline without stating the impact treats the incident as an engineering puzzle rather than a customer harm.
  • Writing the incident report as though it were a postmortem by including blameless retrospective framing, team names, or internal process detail - The postmortem is the internal learning document; the incident report is for customers. Exposing internal process language in a customer-facing report conflates two distinct audiences with incompatible needs and over-discloses engineering detail.
  • Publishing a final incident report with vague commitments like we will look into this when the incident is already resolved - By the time a final report is issued, affected customers expect concrete remediation steps; vague language signals the organization has not yet understood its own failure and erodes the trust the format exists to rebuild.

Failure modes

Section titled “Failure modes”
  • Over-apologizes - the accountability register tips into a string of regret statements that crowd out the factual content customers actually need, turning the report into a performance of remorse rather than a record of the incident - One clear acknowledgment of customer impact is enough; the remaining sections should be factual, specific, and forward-facing - customers need to know what happened and what will change, not how sorry the team is.
  • Over-discloses in the name of transparency - the accessible explanation tips into sharing internal system names, draft hypotheses, team attribution, or speculative root cause detail that creates new confusion or liability without serving the reader - Bound the root cause to the category and mechanism of failure in accessible terms; reserve incomplete or sensitive technical analysis for the internal postmortem.

Instruction

Section titled “Instruction”
Write as a customer-facing Incident Report. Use the canonical structure: Status, Summary, Impact,
Timeline, Root Cause, Resolution, Next Steps. In Status: name the current investigation stage
(Investigating, Identified, Monitoring, or Resolved) and the date and time. In Summary: state in
one to two sentences what service was affected and what customers experienced. In Impact: name
the affected services and the customer population in plain language. In Timeline: give a
chronological list of key events. In Root Cause: explain what caused the failure in terms a
non-engineer can understand - name the category of failure without internal jargon, team names,
or speculative detail. In Resolution: state what was done to restore service. In Next Steps: list
specific, committed remediation actions. Take organizational accountability clearly but do not
name individuals or expose internal team structure. Keep the tone direct and factual. One
acknowledgment of customer harm is sufficient; the rest of the document should be specific and
forward-facing. Do not write this as a postmortem - that is an internal document; this is for
the people who were affected.

Template

Section titled “Template”

See the Incident Report template.

Section titled “Related”

Pairs well with

Section titled “Pairs well with”

Executive, Direct Communicator, Candid, Diplomatic, Problem-Solution, Executive Summary

Avoid with

Section titled “Avoid with”

Playful, Confessional, Reverent

Often confused with

Section titled “Often confused with”

Postmortem, Public Statement

Examples

Section titled “Examples”

Incident Report: #team-standup Blocker Gap - Week 2, Day 11

Section titled “Incident Report: #team-standup Blocker Gap - Week 2, Day 11”

Status

Section titled “Status”

Resolved - Day 11 of 30-day trial, 13:30 Pacific

Summary

Section titled “Summary”

During Week 2 of the async standup trial, a blocked item posted to #team-standup with an @mention was not acted on during the on-call triage window. One engineer’s work was delayed approximately 4 hours while waiting for a dependency to be resolved.

Impact

Section titled “Impact”
  • Services affected: #team-standup coordination channel; on-call blocker-response workflow
  • Engineers affected: 1 engineer directly blocked; 1 dependent workstream stalled
  • Duration: 09:15 Pacific to 13:30 Pacific (4 hours 15 minutes)

Timeline

Section titled “Timeline”
  • 09:15 Pacific - Engineer posted standup update to #team-standup with an @mention flagging a blocked API integration dependency
  • 09:45 Pacific - On-call triage window opened; on-call engineer began channel review
  • 10:05 Pacific - On-call engineer completed triage pass without responding to the blocked item
  • 11:30 Pacific - Blocked engineer escalated via direct message to on-call engineer
  • 11:35 Pacific - On-call engineer located the missed @mention in the channel
  • 11:40 Pacific - Blocker identified and resolved; affected engineer resumed work
  • 13:30 Pacific - Dependent workstream confirmed unblocked; no further impact to other team members

Root Cause

Section titled “Root Cause”

The on-call triage pass did not include a dedicated scan for @mentions. That morning’s channel had 11 posts, several running significantly longer than the three-bullet format calls for - the same pattern flagged as at-risk in the Week 2 status update. The on-call engineer scanned the channel linearly and did not catch the @mention buried in a longer post. There was no secondary check or alert to catch missed mentions before the triage window closed.

Resolution

Section titled “Resolution”

The blocked engineer escalated via direct message. The on-call engineer located the original @mention within 5 minutes, identified the dependency, and provided the needed information in a thread reply. The engineer was unblocked and resumed work within 10 minutes of the direct-message escalation. No other engineers were affected after the gap was closed.

Next Steps

Section titled “Next Steps”
  • Add a dedicated @mention scan as a required step in the on-call triage checklist, implemented before the next triage window (Day 12 morning)
  • Enforce the three-bullet post ceiling to reduce triage scan time: share two exemplar posts in the #team-standup pinned message and demo the format at the Thursday working session
  • Review whether the on-call triage role needs an automated @mention alert at the Day 30 retro, particularly if post volume continues to rise as the team adds the two planned hires