Incident postmortem template for an AI-written change
Last updated
A blameless postmortem template for incidents caused by AI-written changes: the task, the tool, the evidence at merge, and which review step or gate missed it.
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.]
About this template
This section is on the web page only, not in the downloads.
The blameless approach follows Google's SRE book chapter Postmortem Culture: Learning from Failure, which puts the focus on "identifying the contributing causes of the incident without indicting any individual or team". Section 3 is what makes this template specific to AI-written changes: you need to know what the approver could see at the moment they approved, or you can't tell a review failure from an evidence failure.
If you use AI CodeOps, the evidence pack for the change holds most of section 3: the task, the models, the approvals, the findings, the test runs and the delivery. The rollback guide covers section 4's mitigation step.
Frequently asked questions
Should a postmortem blame the AI tool?
No more than it would blame a compiler. The useful question is which part of your process let the change through, and what to change so the next one is caught: a check, a gate, a permission or a review habit.
What makes this different from a normal postmortem template?
Section 3. It records the task the tool was given, the model, and the evidence the approver saw at merge, so you can tell whether the review failed or the evidence was missing or wrong.
Who should write the postmortem?
Someone who was involved, with the requester and the approver both reviewing the draft. Neither of them should be made to feel at fault; their account of what they saw is the most valuable input.
Cite this
AI CodeOps (2026). Incident postmortem template for an AI-written change. https://aicodeops.dev/templates/ai-change-postmortem
This page and its downloads are licensed CC BY 4.0: copy and adapt them for your team, and link back to this page when you publish your version.