---
name: post-mortem
description: Defines a strict, auditable post-mortem workflow after AI mistakes or user corrections. Use when the AI is corrected, a check/test fails, or behavior-level prevention changes are needed.
category: workflow
impact: high
---

# Post-Mortem Instructions

## 🎯 Purpose
Provide a deterministic recovery path after mistakes so failures become explicit, traceable, and preventable.

## 🚨 Prohibitions (Thou Shalt Not)
- **NEVER continue implementation before presenting a post-mortem when corrected.**
- **NEVER edit `.ai/` instructions without explicit user approval.**
- **NEVER write vague "sorry" responses without evidence and root cause.**
- **NEVER propose broad behavior rewrites when a minimal targeted fix is enough.**

## Workflows (Mechanical Procedure)

1. **Pause & Collect Evidence**
   - Capture inputs, commands, files, and outputs that demonstrate the failure.
   - Quote short snippets/log lines proving the issue.

2. **Produce Post-Mortem Report**
   - Include: Summary, Trigger, Evidence, Root cause, Proposed fix, Verification plan.
   - Use the template from `REFERENCE.md`.

3. **If AI behavior/instructions are affected**
   - Propose an explicit skill change:
     - target file path
     - one-line rationale
     - minimal patch snippet

4. **Ask for Explicit Approval**
   - Present the report and patch.
   - Ask for one clear accept/deny decision.
   - Do not edit `.ai/` files before approval.

5. **Apply + Verify**
   - If approved: apply minimal change and run verification.
   - If denied: archive the post-mortem in `tmp/<topic>/<short-title>.md` and propose alternatives.

## ✅ / ❌ Examples

```text
// ❌ FORBIDDEN: empty apology
Sorry, I will remember this next time.

// ✅ REQUIRED: auditable correction path
### Post-Mortem — missing root-skill envelope
- Summary: response omitted mandatory sections
- Trigger: user reported non-compliance
- Evidence: reply missing ack/progress block
- Root cause: response scaffold not enforced
- Proposed fix: update .ai/skills/root-skill/SKILL.md with explicit checklist guard
- Verification plan: verify next 3 responses include mandatory envelope
- Apply?: (pending user approval)
```