Retro

Poka-Yoke Retro

A defect got out. The fix for the defect is the easy part and is usually already done or obvious. This mode is about the harder and more valuable question: what made the mistake available, and what device removes it for good?

Shingo's framing is the whole method here. Do not ask why the person erred, people err, that is a constant. Ask why the process permitted the error to become a defect, and what would have physically stopped it.

1. Separate the three things

People conflate these, and conflating them is why incidents repeat.

• The defect: what the user or system experienced. "Customers were charged twice."
• The mistake: the specific human action that produced it. "The retry path called charge() again without an idempotency key."
• The hazard: the property of the system that made that mistake possible and silent. "charge() accepts an optional idempotency key and succeeds without one."

Fixing the defect ships today. Fixing the mistake helps one code path. Only fixing the hazard prevents recurrence, and the hazard is almost always a missing constraint, not a missing piece of knowledge.

Write all three out explicitly before proposing anything. If you cannot state the hazard as a property of the system, you have not found it yet.

2. Ask why until you reach a constraint

Run the whys, with one discipline: an acceptable terminal answer is a missing constraint, never a missing human quality. If a chain ends in "they forgot," "they didn't know," "they were rushing," or "it wasn't documented," you stopped one step early, keep going and ask why forgetting was possible, why the knowledge was needed at all, why the system accepted the result.

Double charge → retry called charge() twice → the retry path didn't pass an idempotency key → the key is an optional parameter → why is it optional? → it was added later and made optional to avoid breaking callers → there is no compile-time or database-level requirement that a charge be idempotent.

That last line is the hazard, and it is fixable: make the parameter required, or add a unique constraint on (account_id, idempotency_key). Compare it to "the engineer should have passed the key," which is fixable only by hiring different humans.

Also ask the escape question separately: what should have caught this and didn't? Usually there was a device: a test, a review, a type, and it was absent, disabled, or too weak. That gap is a second finding in its own right.

3. Sweep for the class. This is the step that gets skipped

A poka-yoke that fixes one call site is not a poka-yoke. Before proposing anything, find every other place the same mistake is still available. This is almost always where the real value of a retro sits, and it is the step people omit under time pressure.

Search by the shape of the hazard, not by the text of the bug:

• Every other caller of the same function or endpoint.
• Every other function with the same dangerous signature shape, other optional-when-it-should- be-required parameters, other same-type adjacent arguments, other unguarded bulk operations.
• The same pattern in sibling services, other languages in the monorepo, scripts, jobs, and infrastructure code.
• Run python3 ../../scripts/detect_hazards.py --paths <repo> --id <hazard-id>: the ID is the one printed with each finding, to catch instances you would not have thought to grep for.

Report the count plainly: "the same hazard exists at 6 other call sites" changes the conversation about how much the fix is worth.

4. Choose the device by rung

Now propose, using the ladder from the router skill. For an incident that already cost something real, push hard for Control: you have the strongest evidence you will ever have that this mistake happens.

A regression test is genuinely valuable and you should write one. It proves the fix and stops this exact path regressing. But be honest that it is rung 3: it catches the mistake after someone makes it, and only on the path you thought of. If the retro produces only a test, say so, and say what a Control-rung device would have required.

Beware the fix that is really rung zero wearing a costume: more documentation, a new checklist item, a Slack reminder, a training session, an extra required reviewer. These feel like action and change nothing. If that is genuinely all that is possible, name it as an accepted risk rather than a resolution.

5. Write it up

# Retro · <short title> · <YYYY-MM-DD>

**Defect**: <what was experienced, with blast radius: how many, how much, how long>
**Mistake**: <the specific action taken>
**Hazard**: <the system property that made it possible and quiet>

## Why it was possible
<the chain, ending at a missing constraint>

## Why nothing caught it
<the device that should have existed, was disabled, or was too weak>

## Class sweep
<n other sites where this mistake is still available, list them>

## Devices
| Device | Rung | Covers | Status |
|---|---|---|---|
| <change> | Control | all N sites | proposed |
| <regression test> | Detection | the original path | done |

## Accepted risk
<what remains possible, and why that is acceptable>

Save to docs/poka-yoke/retro-YYYY-MM-DD-<slug>.md, and put a poka-yoke: marker comment at each installed device naming the mistake it prevents. That is what stops a future engineer removing it as dead weight, since by then it will never have fired. See the recording section in audit; do not ask anyone to hand-maintain a registry file.

6. Verify the device before you close it

Prove the fix. Reproduce the original mistake against the new device and show it being refused, then show the correct path still working. A device that was never observed to fire is a belief, not a control, and after an incident, a false sense of protection is the most expensive thing you can ship.

Tone

Write about the system, never the person. Not because it is polite, but because it is more accurate and it is the only version that produces a fix: "the engineer should have been more careful" has no implementation. Shingo's argument was that blaming the operator is precisely how organizations avoid improving the process. Names belong in the timeline if at all; the analysis is about affordances.