# Incident Report

> How to write up an incident so the next person can act on it, not just read it.

- Skill: `vstorm-co/incident-report` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vstorm-co/incident-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vstorm-co/incident-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vstorm-co (https://skillmd.com/u/vstorm-co)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vstorm-co/incident-report

---


# Writing an incident report

An incident report is written for somebody who was not there, reading it under
time pressure, six months later. Everything below follows from that.

## Order

Impact first. Who was affected, for how long, and what they could not do. A
report that opens with architecture makes the reader work to find out whether
it matters.

Then the timeline: what happened, in order, with times. Then the cause. Then
what is being changed.

## Rules

**Times are absolute and in UTC.** "Twenty minutes later" forces the reader to
do arithmetic while comparing two reports.

**Name systems, not people.** "The deploy job did not wait for the migration"
is actionable. "Marek deployed too early" is not, and it makes the next person
quieter about their own mistakes.

**Separate what is known from what is believed.** Write "we think" where it is
a theory. A report that reads as certain and is wrong is worse than one that
says which part is a guess.

**Every action item has an owner and a date**, or it is not an action item -
it is a wish. Load `template.md` for the structure to fill in.

## What not to do

Do not write "human error" as a cause. It is where the investigation stops
being useful: a system that a tired person can break at 3am is the finding.