incident-response

name	incident-response
description	Produces an INCIDENT.md (symptom + timeline + evidence-grounded diagnosis + remediation with observed restoration + blameless postmortem + follow-ups); primes the observability + security + compliance gates. Use to record and learn from an incident.

incident-response

The incident producer of the ops domain — it writes an INCIDENT.md: the symptom (observed signal, time, impact), the timeline, an evidence-grounded diagnosis (root cause), the remediation with the service observed back to the expected state, and a blameless postmortem with follow-up actions. Its two halves verify differently: the remediation by Observation (the service was observed restored — health green, metric normal), the postmortem record by Review (complete, blameless, follow-ups tracked). A still-degraded incident is marked in-progress/mitigated, never closed "resolved" without the observed restoration — no fabricated all-clear.

What this does / does not do

Does: resolve the incident-response sub_target, write an INCIDENT.md (symptom + timeline + root-caused diagnosis + remediation with observed restoration + blameless postmortem + follow-ups), and a receipt; record any security/data dimension + disclosure path. Does not: prevent incidents (that is the deploy rollback / runbook it may invoke), execute the remediation itself (an operator does, observed), assign blame (the postmortem is blameless), or close an incident still observed degraded.

When NOT to use

• The work is a standing operational procedure (how to do X safely) — that is runbook; incident-response handles the unplanned event (and may invoke that runbook).
• The work is planning a deploy/rollback — that is deployment; incident-response records what happened when one went wrong.
• There is no incident — a hypothetical drill writes a runbook, not an incident record.
• A current INCIDENT.md for this incident still fits and nothing changed — append to it; do not rewrite the record.

Reference Routing

Situation	Reference
The INCIDENT.md contract template	references/incident-template.md
Per-sub_target must-declares · overlay · vocabulary	../acceptance/sub-targets.md · ../acceptance/overlay.md · ../vocabulary.md
The procedure / change involved	runbook · deployment

Inputs

• The incident facts — the alert/symptom, the timeline, what was observed (logs/metrics), the actions taken, the impact/severity.
• The relevant runbook / DEPLOY-PLAN.md if the incident relates to a procedure or a change.
• The ops domain pack (../vocabulary.md, ../acceptance/) + state/intake.json.

How to do it

1. Record the symptom + severity: the observed signal that opened the incident, when it started, and the impact (who/what affected, severity). Anchor on observation, not assumption.
2. Build the timeline: the sequence of events with timestamps — detection, actions, effects — from the evidence (logs, metrics, chat). The timeline is the spine the diagnosis hangs on.
3. Diagnose the root cause: the cause, tied to specific evidence in the timeline. A cause you cannot point to is a hypothesis — label it as such; do not state speculation as the cause.
4. Record the remediation + observed restoration: what was done, and the observable that confirms the service is back to the expected state (health green, metric normal). If still degraded, mark in-progress/mitigated — not resolved.
5. Handle the security/data dimension: if data or a breach is involved, scope it and note the disclosure/notification path (the security + compliance gates); record the audit trail.
6. Write the blameless postmortem + follow-ups: contributing factors (systemic, not individual), what would have caught it earlier, and follow-up actions each with an owner and a due date.
7. Write INCIDENT.md from references/incident-template.md; name the incident owner.

Gate (before marking complete)

• Symptom (observed signal + time + impact/severity) and a timeline are recorded.
• The root cause is evidence-grounded; speculation is flagged as a hypothesis (observability).
• The remediation's observed restoration is recorded; a degraded service is in-progress, not resolved.
• Any security/data dimension is scoped with a disclosure/notification path (security, compliance).
• The postmortem is blameless and follow-up actions have owners (compliance audit trail).
• The record never claims an all-clear that was not observed.

A gate failure is fixed before lock, not waived — these mirror the observability/security/compliance gates.

Output

• INCIDENT.md at the product root (or ops/INCIDENT.md) — persistence: Spec-Anchored. Symptom + severity · timeline · evidence-grounded diagnosis · remediation + observed restoration · security/data scope · blameless postmortem · follow-up actions (owner + due) · incident owner.
• receipt (<workspace>/receipts/incident-response-receipt-<ts>.json): base schema + sub_target, symptom, severity, root_cause, restored_observed, status, follow_ups, incident_path, gate_checks. persistence: Spec-Anchored.

Proactive Triggers

• A root cause with no evidence: label it a hypothesis and tie the real cause to the timeline — speculation stated as cause misdirects the follow-ups.
• An incident closed while still degraded: mark it in-progress/mitigated; "resolved" requires the observed restoration, not optimism.
• A postmortem naming a person: rewrite it to the systemic contributing factor — the postmortem is blameless or it stops being honest.
• A breach/data incident with no disclosure path: scope it and record the notification path (security + compliance) before closing.

Completion Criteria

Done when: an INCIDENT.md exists with the symptom + severity, a timeline, an evidence-grounded root cause (hypotheses labelled), the remediation with its observed restoration (or an honest in-progress status), any security/data dimension scoped, and a blameless postmortem with owned follow-ups; an incident receipt records the gate checks.

Not done if: the root cause is speculation stated as fact; the incident is closed while observed degraded; a breach has no disclosure path; the postmortem assigns blame; or an all-clear is claimed without observation.

Next step: the follow-up actions become work (their own task cards / runbooks); a recurring incident class feeds a new runbook; deployment carries the fix forward.

Related Skills

• runbook: a standing remediation procedure incident-response may invoke during the event. runbook is proactive (the SOP); incident-response is reactive (the unplanned event + the learning).
• deployment: the change whose rollback incident-response relies on when a deploy caused the incident.
• analyze: structured root-cause analysis (5-whys / fishbone). incident-response may use it for the diagnosis; analyze finds the cause, incident-response records the whole incident + remediation + learning.