Poka-Yoke

# Poka-Yoke: Make the Mistake Unsayable

**People will always make mistakes. That is not the problem worth solving. The problem is

letting a mistake become a defect.**

Shigeo Shingo, a Japanese industrial engineer, worked this out on a switch assembly line in

1961. Workers kept forgetting a spring. The fix was not a reminder: the job was split so the

worker first laid both springs in a dish, then fitted them from the dish. A spring left over

was the error announcing itself, before the unit could move on.

The dish is a device. "Please remember the spring" is not.

The line that does most of the work

> A comment, a docstring, a wiki page, a review checklist, or a line in an instructions file

> saying "don't do X" is **not** a poka-yoke. It is training, and training degrades. A device

> does not. If your fix relies on someone remembering something, keep going.

This applies to your own instructions too. A rule written into a config file competes for

attention with every other rule there and loses a little more as the file grows. A check that

fails the build does not.

What this changes about the output

Given a design, models will readily list what to fix. They rarely state what the fix makes

*impossible*, and that is the difference between advice you agree with and a constraint you

can rely on. That habit is most of what this skill is for.

The other half is refusing to accept a non-device as a fix. "Add validation", "be careful with

this function", "document the invariant" are all rung zero. Each has a real device behind it,

and naming that device is the work.

Axis 1: what happens when the mistake occurs

Rank every finding on this ladder, and say which rung the current code sits on and which rung

your fix reaches.

| Rung | Name | Meaning |

|---|---|---|

| 1 | **Control** | The wrong action cannot be performed. Type error, database constraint, missing permission. |

| 2 | **Warning** | It is possible, but announces itself as it happens. A linter, a runtime assertion, a confirmation you cannot skip. |

| 3 | **Detection** | It happens, and you find out afterwards. Tests, logging, monitoring, code review. |

| 0 | **rung zero** | Telling people to be careful. Docs, comments, "please remember to". |

Detection is not failure; sometimes it is all that is available. But a plan that stops at

Detection should say so, rather than presenting it as prevention.

Axis 2: how the device notices

Shingo's three inspection lenses. They are a checklist for *finding* hazards, not decoration:

- **Contact** — can the wrong thing physically fit? Two adjacent parameters of the same type can be swapped silently. A `string` that should be one of four values. Money as a float.

- **Fixed-value** — is the set complete? A switch with no exhaustiveness check. A config where a missing key silently means "off". An enum handled in three of five places.

- **Motion-step** — is the order right, and did every step happen? A two-phase write with no transaction. A retry with no idempotency key. A resource acquired on one path and released on another.

Inspect at the source

The cheapest place to catch a mistake is where it is made, not where it surfaces. A validation

that runs three layers below the input has already let the bad value travel, and the stack

trace will point at the wrong module. Push the check to the boundary the value crosses.

Designing something new

Mistake-proofing is cheapest before the code has callers. Once it has them, every device is a

migration; before it has them, a device is free.

Work from the call site. A signature that reads fine in isolation often reads terribly where

it is used:

# the mistake is expressible: nothing stops refunding an order that was never paid
def refund(order: dict) -> Refund:
    return payments.refund(order["payment_id"])

# the mistake is no longer expressible
def refund(order: PaidOrder) -> Refund: ...

The moves, roughly in order of how often they apply:

**Make invalid st