Incident review
Write the review of the incident in "$ARGUMENTS" so the team learns from it, as references/incidents.md describes: the question is what in the system let this happen, never who to blame.
Compute with code. Perform every calculation (totals, balances, ratios, variances, projections) with a script — Bash, Python or a spreadsheet formula written to a file — and include the computation alongside the result. Never do arithmetic mentally.
Prerequisites
The record: the timeline, chat log, alerts, graphs and notes the user supplies, as files or pastes. When $ARGUMENTS or the request names a project, use that name as <project> whether or not its folder exists yet in .singularskills/ops/ (create it when you write). With no project named: with exactly one folder there, use it; with several, ask which; with no folder at all, name the project after the affected service in the record (for example checkout) and say so in Decisions. Read .singularskills/ops/<project>/02-slos.md and 04-runbooks.md when they exist.
Append this line to .singularskills/log.jsonl before you write the review (create the folder and file if missing): {"ts":"<ISO timestamp>","skill":"ops-incident-review","workflow":"ops","phase":null,"project":"<project>","event":"started","artifact":"incidents/<date>-<slug>.md","note":""}, where <date> is today as YYYY-MM-DD and <slug> is two to four words naming the topic, never a person.
Process
Check it is not a security incident. If the record shows signs of a breach (unauthorised access, exposed data, an attacker), stop and point the user to /security-incident-response.
People by role, never by name, even when the user or the record names them: "the deploying engineer", "the on-call engineer", "the incident commander". Rewrite names to roles everywhere: in the review and in your reply to the user, including when you explain that the review is blameless (say "the deploying engineer", not the person's name).
Impact: how long users were affected, which journeys, roughly how many users, and the error budget consumed, each computed from the record with a script written to .singularskills/ops/<project>/ and included beside the result, or not measured. Scripts read the user's files where they keep them and write results under .singularskills/.
Timeline: times, what was seen, what was done, by role, from the first sign to full recovery; mark when the problem started, when it was detected, when it was mitigated and when it was resolved.
Contributing factors, several, not one root cause. Each tied to a part of the system or process: the tool, the guard that was missing, the alert that fired late, the runbook that was stale, the review that did not happen. Human error is a starting point, not a finding: when a person did something that caused harm, ask what made it easy to do and hard to notice, and write that as the factor.
Where the system misled or failed the responders: confusing output, missing signals, steps that did not work, information they did not have.
What went well, so it is kept.
Action items that change the system or the process, each with an owner (a role or team) and a date. Never retraining, discipline or "be more careful" as the fix for a systemic gap; if the user asks for one, explain why a guard in the system works where a reminder does not, and write the guard.
Write the review to .singularskills/ops/<project>/incidents/<date>-<slug>.md with sections Summary, Impact, Timeline, Contributing factors, Where the system misled us, What went well and Action items.
Output
The review written to .singularskills/ops/<project>/incidents/<date>-<slug>.md. Present the contributing factors and the action items first, with their owners. Name nobody in the reply either: people by role only.
After you have written the review, append the started line of Prerequisites to .singularskills/log.jsonl with "event":"finished": {"ts":"<ISO timestamp>","skill":"ops-incident-review","workflow":"ops","phase":null,"project":"<project>","event":"finished","artifact":"incidents/<date>-<slug>.md","note":""}.
The review opens with this frontmatter (agent is the agent you run in, or unknown; this utility has no gate, so phase is null and gate is none):
---
skill: ops-incident-review
workflow: ops
phase: null
project: <project>
started: <ISO timestamp>
finished: <ISO timestamp>
agent: <the agent you run in, or "unknown">
gate: none
---
The review ends with ## Decisions and ## Open questions, in this shape:
## Decisions
- <what was chosen> — <why> — <what was rejected>
## Open questions
- <what a reviewer must settle>
1---2name: ops-incident-review3description: Write a blameless postmortem of a production outage or incident — impact, timeline, several contributing factors instead of one root cause, where the system misled the responders, what went well, and action items on the system with owners. Use when a production incident is over and the team needs to understand it. Not for project post-mortems; see /project-management-post-mortem.4metadata:5 source: https://skillmd.com/skills/bromso/ops-incident-review6 argument-hint: "[project] [incident]"7---89# Incident review1011Write the review of the incident in "$ARGUMENTS" so the team learns from it, as `references/incidents.md` describes: the question is what in the system let this happen, never who to blame.1213**Compute with code.** Perform every calculation (totals, balances, ratios, variances, projections) with a script — Bash, Python or a spreadsheet formula written to a file — and include the computation alongside the result. Never do arithmetic mentally.1415## Prerequisites1617The record: the timeline, chat log, alerts, graphs and notes the user supplies, as files or pastes. When `$ARGUMENTS` or the request names a project, use that name as `<project>` whether or not its folder exists yet in `.singularskills/ops/` (create it when you write). With no project named: with exactly one folder there, use it; with several, ask which; with no folder at all, name the project after the affected service in the record (for example `checkout`) and say so in Decisions. Read `.singularskills/ops/<project>/02-slos.md` and `04-runbooks.md` when they exist.1819Append this line to `.singularskills/log.jsonl` before you write the review (create the folder and file if missing): `{"ts":"<ISO timestamp>","skill":"ops-incident-review","workflow":"ops","phase":null,"project":"<project>","event":"started","artifact":"incidents/<date>-<slug>.md","note":""}`, where `<date>` is today as `YYYY-MM-DD` and `<slug>` is two to four words naming the topic, never a person.2021## Process22231. **Check it is not a security incident.** If the record shows signs of a breach (unauthorised access, exposed data, an attacker), stop and point the user to `/security-incident-response`.24252. **People by role, never by name,** even when the user or the record names them: "the deploying engineer", "the on-call engineer", "the incident commander". Rewrite names to roles everywhere: in the review and in your reply to the user, including when you explain that the review is blameless (say "the deploying engineer", not the person's name).26273. **Impact:** how long users were affected, which journeys, roughly how many users, and the error budget consumed, each `computed` from the record with a script written to `.singularskills/ops/<project>/` and included beside the result, or `not measured`. Scripts read the user's files where they keep them and write results under `.singularskills/`.28294. **Timeline:** times, what was seen, what was done, by role, from the first sign to full recovery; mark when the problem started, when it was detected, when it was mitigated and when it was resolved.30315. **Contributing factors, several, not one root cause.** Each tied to a part of the system or process: the tool, the guard that was missing, the alert that fired late, the runbook that was stale, the review that did not happen. **Human error is a starting point, not a finding:** when a person did something that caused harm, ask what made it easy to do and hard to notice, and write that as the factor.32336. **Where the system misled or failed the responders:** confusing output, missing signals, steps that did not work, information they did not have.34357. **What went well,** so it is kept.36378. **Action items that change the system or the process,** each with an owner (a role or team) and a date. Never retraining, discipline or "be more careful" as the fix for a systemic gap; if the user asks for one, explain why a guard in the system works where a reminder does not, and write the guard.38399. **Write the review** to `.singularskills/ops/<project>/incidents/<date>-<slug>.md` with sections **Summary**, **Impact**, **Timeline**, **Contributing factors**, **Where the system misled us**, **What went well** and **Action items**.4041## Output4243The review written to `.singularskills/ops/<project>/incidents/<date>-<slug>.md`. Present the contributing factors and the action items first, with their owners. Name nobody in the reply either: people by role only.4445After you have written the review, append the `started` line of Prerequisites to `.singularskills/log.jsonl` with `"event":"finished"`: `{"ts":"<ISO timestamp>","skill":"ops-incident-review","workflow":"ops","phase":null,"project":"<project>","event":"finished","artifact":"incidents/<date>-<slug>.md","note":""}`.4647The review opens with this frontmatter (`agent` is the agent you run in, or `unknown`; this utility has no gate, so `phase` is `null` and `gate` is `none`):4849```yaml50---51skill: ops-incident-review52workflow: ops53phase: null54project: <project>55started: <ISO timestamp>56finished: <ISO timestamp>57agent: <the agent you run in, or "unknown">58gate: none59---60```6162The review ends with `## Decisions` and `## Open questions`, in this shape:6364```markdown65## Decisions66- <what was chosen> — <why> — <what was rejected>6768## Open questions69- <what a reviewer must settle>70```