# Incident postmortem template for an AI-written change

> Copy this into your incident tracker or wiki. Replace [brackets], delete sections you don't need, and delete this note. Keep it blameless: describe what people and tools did and what they could see, not who should have known better.

- **Incident:** [ID and short title]
- **Severity:** [SEV1 / SEV2 / SEV3]
- **Date and duration:** [YYYY-MM-DD, from HH:MM to HH:MM UTC]
- **Author:** [name]
- **Reviewed by:** [names]
- **Status:** [draft / reviewed / actions complete]

## 1. Summary

[Two or three sentences: what broke, who was affected, for how long, and what caused it.]

## 2. Impact

- **Users or customers affected:** [number or share, and how you know]
- **What they experienced:** [errors, wrong data, slowness, data exposure]
- **Data affected:** [none / which data, and whether any left your systems]
- **Cost:** [credits, refunds, engineering time, if known]

## 3. The change

| Question                                           | Answer                                         |
| -------------------------------------------------- | ---------------------------------------------- |
| Pull request and commit                            | [links]                                        |
| How was it written?                                | [coding agent / AI assistant / person]         |
| Tool and model                                     | [name and version]                             |
| The task the tool was given                        | [paste it or link to it]                       |
| Did the change do only what the task asked?        | [yes / no: what else it did]                   |
| Who requested it, and who approved it?             | [roles; they should be different people]       |
| Which tests ran on the merged version?             | [link to the run; were any skipped?]           |
| Did the test diff delete, skip or loosen anything? | [yes / no]                                     |
| Open review or security findings at merge          | [none / list and how they were triaged]        |
| Was the change edited after approval?              | [yes / no; was it re-approved?]                |
| What did the approver see when they approved?      | [the evidence on the pull request at the time] |

## 4. Timeline

All times UTC.

| Time  | What happened                                    |
| ----- | ------------------------------------------------ |
| HH:MM | Task given to the tool                           |
| HH:MM | Pull request opened                              |
| HH:MM | Approved by [role]                               |
| HH:MM | Merged and deployed                              |
| HH:MM | First sign of the problem: [alert, ticket, user] |
| HH:MM | Incident declared                                |
| HH:MM | Mitigated: [revert, flag off, rollback]          |
| HH:MM | Resolved                                         |

## 5. Root cause and contributing factors

**What was wrong with the change:** [the actual defect, e.g. an error swallowed and replaced with an empty result]

**Why it got through.** For each layer, say whether it could have caught this and why it didn't.

| Layer                 | Could it have caught this? | Why it didn't                                  |
| --------------------- | -------------------------- | ---------------------------------------------- |
| The task              | [yes / no]                 | [ambiguous, missing a constraint]              |
| The tool's own checks | [yes / no]                 |                                                |
| Tests                 | [yes / no]                 | [no test for this case, test was weakened]     |
| Automated review      | [yes / no]                 | [not run, finding dismissed, out of scope]     |
| Human review          | [yes / no]                 | [too large, risky file skimmed, self-approved] |
| Quality gates         | [yes / no]                 | [gate missing, gate passed on stale evidence]  |
| Staging or canary     | [yes / no]                 |                                                |
| Monitoring and alerts | [yes / no]                 | [how long until someone noticed]               |

## 6. What went well

- [e.g. The revert was one click and took four minutes.]

## 7. Actions

Prefer actions that change a system over actions that ask people to be more careful.

| Action                                                       | Type                  | Owner  | Due          | Ticket |
| ------------------------------------------------------------ | --------------------- | ------ | ------------ | ------ |
| [e.g. Add a test for an empty upstream response]             | [test]                | [name] | [YYYY-MM-DD] | [link] |
| [e.g. Require code owner review for the billing module]      | [gate or permission]  | [name] | [YYYY-MM-DD] | [link] |
| [e.g. Add "no silent fallbacks" to the review checklist]     | [review practice]     | [name] | [YYYY-MM-DD] | [link] |
| [e.g. Restrict the agent's write access to its own branches] | [agent configuration] | [name] | [YYYY-MM-DD] | [link] |

## 8. Lessons

[What would you tell another team using the same tools? One paragraph.]

---

From https://aicodeops.dev/templates/ai-change-postmortem · Last updated 2026-10-24 · Licensed CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)