retro

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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.

| Rung | For this incident, that would mean |
|---|---|
| **Control** | Required parameter · database unique constraint · type that cannot represent the bad state · CI check that cannot be merged past |
| **Warning** | Lint rule · runtime assertion · alert at the moment of the action |
| **Detection** | Regression test · monitor · reconciliation job |
| **None** | "Added a note to the runbook" · "reminded the team" · "added a review checklist item" |

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

```markdown
# 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

From rainmanjam/poka-yoke, MIT.

More from rainmanjam/poka-yoke