# Post-Mortem Skill (Vanilla Reference)

Run an orchestration retrospective after a plan has been executed, then fold the lessons back into your local skills and gates so they don't rot.

> **Vanilla reference skill — adapt the placeholders to your project.** Everything below uses generic placeholders (`<plan>`, `<base branch>`, `<authority doc>`, `<report archive>`). Swap them for your project's real names, paths, and conventions when you adopt it.

## Purpose

After a plan's changes have landed, this skill asks a single question: **where did the process churn, and why?** Its output is not a document that gets filed away — its output is concrete edits to your skills and gates, which you apply in the same pass. This is the self-improvement loop that keeps a project's local skills current. Without it, they rot.

## First principle: this is an orchestration retrospective, not a code review

Code-level findings were already caught and fixed during review of the change itself. They do **not** reappear here. A post-mortem that re-lists "this function should have handled the empty case" is doing the reviewer's job over again and adds no value.

This pass looks one level up, at the *process*:

- Where did work churn, stall, or get redone?
- Which handoff was ambiguous?
- Which instruction was misread, and was the instruction itself at fault?
- Where did a plan's example fail to constrain the outcome?

If a finding is "the code should have done X," it belongs in code review, not here. If a finding is "the plan/skill/gate should have made X happen automatically," it belongs here.

## First principle: the output IS skill and gate edits — you apply them

This is the loop that keeps the local skills from rotting; without it, they rot. So the deliverable is not a list of recommendations to park for later. It is a set of edits to the actual skill files and gate configuration, made during this pass. If you finish the retrospective and the skills are unchanged, the loop did not run.

- **Small tightenings** edit the skill in place — a sharper example, one more forbidden pattern, a clearer acceptance line.
- **Larger reshapes** (a skill needs restructuring, a new gate, a workflow change) spin up their own plan → execute cycle rather than being crammed in here. Note them, open the follow-up, and move on.

## Step 0: re-sync the base branch FIRST

Before analyzing anything or proposing any fix, re-sync `<base branch>` and check what has already landed.

Another run — a parallel effort, an earlier post-mortem, a teammate — may have already shipped the exact skill edit you are about to recommend. **Re-recommending an already-shipped fix is the single largest source of noise** in this process. Pull the base branch, read the current state of each skill you intend to touch, and only then decide what still needs changing.

## Step 1: classify each task's gate verdict

For every task in the plan, look at its **inlined pattern** (the example the task was told to match) and its **forbidden list** (the patterns it was told to avoid). Classify the outcome and route the fix to the right place:

| Verdict | What happened | Where the fix goes |
|---|---|---|
| **Drifted** | The agent ignored the inlined pattern and did its own thing. | Tighten the plan's inlined example so the intended shape is unmistakable. |
| **Forbidden-list incomplete** | A bad pattern slipped through because nothing forbade it. | Tighten the authority doc / conventions so the pattern is named and banned. |
| **Pattern ignored despite being present** | The pattern was right there and still wasn't followed. | Tighten the executor's self-audit or the central compliance check (e.g. the shared grep) so it's caught mechanically. |

The verdict determines the destination. Drift is a planning problem, a slipped-through pattern is an authority-doc problem, and an ignored-but-present pattern is an enforcement problem. Fixing the wrong layer wastes the lesson.

## Step 2: write the fixes

With the base branch re-synced (Step 0) and verdicts assigned (Step 1), make the edits:

1. For each verdict that survived the re-sync (i.e. isn't already fixed on the base branch), apply the routed fix.
2. Keep small tightenings inline — edit the skill, the authority doc, or the gate directly.
3. For anything that needs more than a tightening, open a follow-up plan instead of forcing it in here.
4. Keep every skill **project-local and constantly updated.** A skill that lives with the project and changes every time the process teaches you something is a skill that stays true. A skill copied off somewhere and left untouched is a skill that drifts from reality until it misleads.

## Step 3: archive and clean up

Close the loop:

- Write the retrospective to `<report archive>` so the reasoning behind each edit is recoverable later.
- Clean up the working artifacts of the run (worktree, scratch branches, temporary files) per the cleaning-up skill.

## Anti-patterns to avoid

- **Code "shoulda" findings.** If it's a code fix, it belonged in review and is out of scope here.
- **Recommending a fix without re-syncing first.** You will re-recommend things that already shipped.
- **Parking recommendations instead of applying them.** The output is edits, not a wishlist.
- **Routing a fix to the wrong layer.** A drift is not fixed by adding a grep; a missing ban is not fixed by rewording an example.
- **Cramming a large reshape into an inline edit.** Give it its own plan → execute cycle.
- **Letting skills go stale.** Local and constantly updated is the whole point.

## Checklist

- [ ] Base branch re-synced before any analysis or proposal.
- [ ] Every task's gate verdict classified (drifted / forbidden-list incomplete / pattern ignored).
- [ ] Each surviving verdict routed to the correct layer and fixed.
- [ ] Small tightenings applied inline; larger reshapes spun into their own plan.
- [ ] Skills left project-local and current.
- [ ] Report archived; run artifacts cleaned up.