---
alwaysApply: false
globs: ["**/*"]
description: "One written record per incident: timestamps, impact, owned follow-ups. Use when production broke or a user reports a fault."
---

# Incident Record

**Produce one written record per incident.** One incident, one record, in the
place the team already keeps its work. The record states:

- when the failure started, when it was detected, when it was mitigated, and
  when it was resolved — each as a timestamp with a time zone;
- whether detection came from a signal or from a user report, named exactly;
- who was informed, and at what time;
- what users could not do, in the words a user would use;
- how many users or requests were affected, or the method used to estimate it;
- at least one follow-up change, each with one named owner and a due date.

**Separate mitigation from resolution.** Mitigation is the moment users could
work again. Resolution is the moment the cause was removed. Recording one
timestamp for both hides how long the product ran on a workaround.

**Record the detection source honestly.** A fault a user reported first means
the signals missed it. Write that, and make one follow-up the missing signal.

**Write the cause as a chain, not a culprit.** Name the change, the condition,
and the missing check that let it reach users. Never name a person as the
cause. A record that blames someone stops the next record from being written.

**Produce the follow-ups where other work is tracked.** Copy them into the
team's normal backlog with owner and due date. A follow-up that lives only in
the incident record is not tracked.

**Feed the outcome back into the product.** A fault a user reported means the
failure was invisible, so the change set includes the signal that would have
caught it, a test that fails without the fix, and one line added to the
operator documentation.

**A reviewer checks:**

- the record exists within 5 working days of the incident `[ASSUMPTION A-8]`;
- it states whether detection came from a signal or from a user report;
- mitigation and resolution carry separate timestamps;
- the follow-up items appear in the team's normal tracker, each with an owner
  and a due date;
- the user-visible impact is stated in user terms, not as an error class;
- no person is named as the cause.