A post-mortem template for regressions caused by AI coding agents

By Shamaz Khan · 18 Nov 2026 · 5 min read

TL;DR

AI-caused regressions have a recognisable shape: the change was small, the diff was bigger, and nothing checked the difference. A post-mortem that only asks "what broke?" misses the lesson. Use this template instead.

The template

## Summary
What broke, for whom, for how long.

## The task
What the agent was asked to do (paste the prompt or ticket).

## What changed
Files in the task's scope:     ...
Files changed outside it:      ...   <- usually where the bug is
Tests or checks edited:        ...

## Why it wasn't caught
- Review:   what the reviewer looked at
- Tests:    what they covered, what they didn't
- Rules:    which rule the agent was told, and whether anything checked it

## Guardrail added (at least one)
- [ ] New lock:      stet lock add "..." --cmd "..."
- [ ] Protected path: --protect "..."
- [ ] Decision logged: stet decide "..." --why "..."
- [ ] Scope habit:   tasks in this area use --allow "..."

## Follow-ups
Owner, date.

Worked example (illustrative)

Summary: CSV exports lost their header row for 4 hours.

Task: "Add a date filter to the reports page."

Changed outside scope: src/export/csv.ts. The agent refactored the export helper while adding the filter.

Why it wasn't caught: no test checked the export output, and the reviewer focused on the filter UI.

Guardrails added:

stet lock add "CSV export format" --snapshot "node scripts/sample-export.js"
stet decide "Export format is a contract with customers" --why "Clients import it into their own tools"

Keep it blameless

The agent did what agents do. The useful question is which check was missing, and the useful outcome is that this class of mistake can't happen silently again.

FAQ

How do I write a post-mortem for an AI-caused bug?

Record the task, list the files changed inside and outside its scope, explain why review and tests missed it, and finish with at least one new guardrail such as a lock, a protected path or a logged decision.

Who is responsible when an AI agent introduces a bug?

Treat it blamelessly: the gap is usually a missing check. Fix the process so the same kind of change is caught automatically next time.

What is the most common cause of AI coding regressions?

Changes outside the requested task: refactors, "tidying" and edits to shared helpers that the review did not focus on.

Put guardrails on your AI coding agent

Stet is a free, open-source CLI and MCP server for Claude Code, Cursor, Codex and Copilot. It runs locally: no account, your code never leaves your machine.

npx stet-cli init · Install · Setup guide · GitHub

Related