| name | incident-communication |
| version | 0.1.0 |
| description | Write clear, empathetic incident status updates for any phase of an incident (investigating, identified, monitoring, resolved). Use when the user mentions "incident update," "status update," "outage communication," "write an incident," "investigating update," "post-incident update," or needs to communicate a service disruption to users. |
Incident Communication
Write status page updates that are clear, honest, and useful — for any phase of an incident.
When to Use
- "write an incident update"
- "we have an API outage, help me communicate it"
- "draft a resolved update for the database incident"
- "our webhooks are delayed, what should I post?"
Workflow
1. Check for Context
Read .agents/status-page-context.md if it exists. Use it for:
- Tone and voice — match the team's communication style
- Components — reference the correct component names
- Severity levels — calibrate urgency appropriately
- Update cadence — respect the team's SLA for update frequency
If the file doesn't exist, suggest running the status-page-context skill first. Proceed without it if the user wants to skip.
2. Determine the Phase
Ask the user which phase they're in if not obvious from their message:
| Phase | When | Purpose |
|---|
| Investigating | Something is wrong, cause unknown | Acknowledge the issue, set expectations |
| Identified | Root cause found, fix in progress | Explain what's happening, share the plan |
| Monitoring | Fix deployed, watching for stability | Confirm the fix, set recovery expectations |
| Resolved | Incident is over | Summarize what happened with exact timeframes |
3. Gather Incident Details
For any phase, you need:
- What's affected — which components/services (use names from context if available)
- What's the user impact — what are users experiencing? (errors, slowness, data loss)
- What's NOT affected — critical for reducing panic
- What's being done — current actions being taken
Additional details by phase:
- Investigating: When did it start? Who reported it?
- Identified: What's the root cause? What's the fix plan? ETA?
- Monitoring: What fix was deployed? How long will monitoring last?
- Resolved: Exact start/end times (UTC). What was the root cause? Will there be a postmortem?
4. Write the Update
Follow these principles (in priority order):
Principle 1: Scope the blast radius immediately
The first sentence should tell users what's affected AND what's not.
Do: "REST API requests are returning elevated 5xx errors. The dashboard and webhook delivery are operating normally."
Don't: "We are investigating reports of degraded performance for some services."
Principle 2: Be specific about user impact
Describe what users are experiencing, not just what's broken internally.
Do: "Deployments created between 11:20 and 15:14 UTC may be failing. Existing deployments are unaffected."
Don't: "We are experiencing an issue with our deployment pipeline."
Principle 3: Give actionable guidance when possible
If users can do something to mitigate, tell them.
Do: "If you're seeing errors, redeploying will resolve the issue for your project."
Don't: "We are working on a fix."
Principle 4: Include timestamps in UTC
Every update should reference when things happened.
Do: "Starting at 14:25 UTC, iDEAL transactions began failing."
Don't: "We recently noticed some issues."
Principle 5: Set expectations for the next update
Tell users when they'll hear from you again.
Do: "We'll post another update within 30 minutes or sooner if the situation changes."
Don't: (silence)
Principle 6: Resolved updates summarize the full story
Include exact time window, what happened, what was done, and whether a postmortem will follow.
Do: "Between 18:00 and 18:23 UTC, the REST API experienced elevated error rates (peak 12% of requests) caused by a misconfigured load balancer rule. The rule was rolled back at 18:19 UTC and error rates returned to normal by 18:23 UTC. We'll publish a full postmortem within 48 hours."
Don't: "This incident has been resolved."
5. What to Communicate Next
After writing the update, always tell the user what comes next:
- After investigating: "When you identify the cause, run this skill again for an 'identified' update."
- After identified: "Once the fix is deployed, run this skill for a 'monitoring' update."
- After monitoring: "When you're confident the fix is stable, run this skill for a 'resolved' update."
- After resolved: "Consider writing a postmortem — use the
postmortem skill."
Phase Templates
Investigating
[Component] is experiencing [user-visible impact] starting at [time UTC].
[What is NOT affected].
We are investigating the cause and will provide an update by [time/timeframe].
Identified
We've identified the cause of [brief description of issue affecting Component].
[Root cause in plain language].
We are [action being taken] and expect [recovery ETA or "will update when we have an ETA"].
[What users can do in the meantime, if anything].
Next update by [time/timeframe].
Monitoring
A fix for [brief issue description] has been deployed at [time UTC].
[What the fix was, in one sentence].
We are monitoring for stability and will resolve this incident if no further issues arise within [timeframe].
[Any user action needed, e.g., "no action needed" or "you may need to retry failed requests"].
Resolved
Between [start time] and [end time] UTC, [Component] experienced [user-visible impact].
[Root cause in 1-2 sentences].
[What was done to fix it].
[Impact summary: % of users/requests affected, if known].
[Postmortem commitment: "We'll publish a detailed postmortem within [timeframe]" or "No further action needed"].
Anti-patterns to Avoid
| Anti-pattern | Why it's bad | Instead |
|---|
| "We apologize for any inconvenience" | Empty corporate filler | State impact honestly and what you're doing |
| "Some users may experience issues" | Vague, unhelpful | Specify what users see and who's affected |
| "We are continuing to investigate" (repeated) | No new information | Share what you've learned, even if partial |
| "This incident has been resolved" (with no details) | Users don't know what happened | Summarize timeline, cause, fix, and impact |
| "Please be patient" | Patronizing | Give an ETA or next update time |
| Copy-pasting the same update multiple times | Looks lazy, erodes trust | Each update should add new information |
Related Skills
status-page-context — Set up the context document this skill reads (tone, components, severity)postmortem — Write a detailed postmortem after a resolved incidentmaintenance — Write planned maintenance announcements (not incidents)status-report — Write periodic health reports
