---
name: "incident_comms"
description: "Write status updates during production incidents: severity framing that informs without panicking, update cadence people can rely on, what to say when you genuinely do not know, and turning the incident thread into a postmortem summary afterward. Use when an outage or degradation needs a status page update, when customers need to hear something and nobody knows what to say, or when an incident thread needs to become a postmortem."
---

# Incident Comms

## Purpose

When production breaks, the communication is what customers actually experience. They do not see the remediation. They see whether you told them, how fast, and whether the update was honest. This skill produces status updates that say what is broken in user terms, who it affects, what you are doing, and when the next update lands. It is scoped to writing updates, not to running the incident (see `incident_response` for the full process: roles, mitigation, postmortem with owned action items).

## Workflow

### 1. Frame severity in plain user terms

Do not open with the internal severity code and stop. Customers decide whether they care from the impact sentence. Lead with impact, tag severity as a fact.

Pattern: `<what is broken in user terms> for <who it affects> (SEVn).`

Good: "Logins are failing for all users in the EU region (SEV1)."
Bad: "SEV1 incident declared." / "Some users may be experiencing intermittent issues."

Severity framing without panic means describing exactly the current observed scope, no adjectives beyond what the facts support. Say "30% of checkout attempts fail", not "checkout is severely degraded". If the scope is unknown, say so: "We are still measuring impact; current reports are limited to the EU region."

Resist severity inflation. If everything is SEV0, nothing is. One wrong call is cheap to fix: downgrade publicly in the next update rather than leaving it inflated.

### 2. Pick the stage and write the update

Nearly every status page convention uses the same four stages. Each answers one question:

| Stage | Question | Content |
|---|---|---|
| Investigating | Do you know? | Confirm the symptom in user terms. Commit to a next update time. No cause, no ETA. |
| Identified | Do you know why? | What is broken, who it affects. A fix is underway. Still no promised ETA unless you are certain. |
| Monitoring | Is it fixed? | The fix is deployed and you are watching. Say what recovery looks like so users can verify. |
| Resolved | Is it over? | Confirm normal service. State duration and scope. Say whether a postmortem follows. |

The stage most teams get wrong is Investigating. It feels empty to post "we are looking into it", so they wait until they have something substantial, and customers guess for forty minutes. The first update is not there to inform. It is there to tell people they do not need to open a support ticket. Post it within 5-15 minutes of detection, even with zero diagnosis.

Do not skip Monitoring and jump to Resolved. If the fix regresses and you reopen an incident you declared over, the credibility cost is far larger than one more update.

### 3. Set the cadence and keep it

| Severity | Update every | Where |
|---|---|---|
| SEV0 / SEV1 | 30 minutes | Status page, email subscribers, in-app |
| SEV2 | 1 hour | Status page, subscribers |
| SEV3 | On meaningful change only | Status page |
| SEV4 | Direct to affected customer | Support channel, not the status page |

Cadence is the promise you are actually making. The content matters less than posting when you said you would.

- **Post on schedule even with nothing new.** "Still investigating, no change, next update in 30 minutes" is a complete update. Silence reads as abandonment. Missing a promised update does more trust damage than the outage itself in most cases.
- **Promise next-update time, not recovery time.** A missed ETA converts a technical problem into a trust problem. The next update time is entirely within your control.

### 4. Say the hard version of "we do not know"

Three templates for honest ignorance:

- **Cause unknown:** "We have confirmed the symptom [symptom]. We do not yet know the cause. Next update in [30 min]."
- **Scope unknown:** "We are still measuring impact. Current reports are limited to [region/product]. If you are affected elsewhere, reply here."
- **ETA unknown:** "We cannot give a recovery time yet. Next update in [30 min]."

Never speculate on cause in the first update. Early theories are usually wrong, and correcting a public diagnosis costs more trust than twenty minutes of not naming one. Saying "we do not know yet" paired with a concrete next-update time is a complete, professional answer.

### 5. After the incident: turn the thread into a postmortem summary

For SEV2 and above, publish a postmortem. Mine the update thread for its skeleton: it already has the timeline.

Postmortem summary structure:

1. **Summary** (one line): what broke, for how long, for whom.
2. **Timeline**: copy from the update thread, trimmed. Each stage transition already has a timestamp.
3. **What broke**: the root cause, stated plainly. "A configuration change caused 40 minutes of failed logins" beats hedges and beats a long apology.
4. **What changes**: the concrete fixes or process changes that prevent recurrence. Each gets an owner.
5. **Impact**: duration, scope, and whatever was lost (revenue, data, work), stated without minimization.

Say what happened plainly, without minimizing it or performing contrition. One sentence of apology, then facts. Customers deciding whether to keep trusting you are looking for evidence you understand why, and precision is what earns that.

## Output Contract

Given: severity, symptom in user terms, affected scope, current stage, and what is known/unknown.

Produce: a status page update (title, body, stage label) that a comms lead can paste with no editing, plus the next-update time. For Resolved stage, produce the postmortem-summary skeleton with the timeline filled from the thread.

Hard requirements on every update:

- Impact described in user terms in the first sentence.
- Stage stated explicitly.
- Next-update time promised; no uncertain ETA promised.
- No speculation on cause before Identified.
- No hedging phrases ("some users may be experiencing", "intermittent issues") when the symptom is confirmed.
- No marketing voice ("working hard to deliver the best experience"). Plain, specific, slightly boring.

## Operating Rules

1. The person writing updates is not the person fixing the incident. Assign a comms role at SEV1/SEV0; the responder deep in the problem is the worst-placed writer.
2. Updates land on the status page first, one canonical URL, hosted away from the infrastructure that is failing. Email subscribers and in-app follow.
3. Internal notes and customer updates are separate documents. Responders' hypotheses stay internal; the status page carries only confirmed facts.
4. Naming a dependency is fine as fact. Presenting it as absolution is not; customers bought availability from you.
5. Legal and disclosure constraints apply to security incidents; the update cadence still applies, the content just carries what counsel cleared. See `references/templates.md` for the security-incident variant.
6. Scenario templates live in `references/templates.md`. Adapt them rather than pasting verbatim. A template's value is stopping you from composing prose at 3am, not that the sentences are optimal for your product.