Poka-Yoke: Mistake-Proofing for Software

Shigeo Shingo's insight, from the Toyota Production System: people will always make mistakes; that is not the problem worth solving. The problem is letting a mistake become a defect. So you stop trying to make humans more careful and start redesigning the work so the mistake either cannot physically happen or announces itself immediately.

A poka-yoke ("poh-kah yoh-kay", ポカヨケ) is a device: a jig, a shape, a counter: not an instruction. In software: a type, a constraint, a hook, a schema, a state machine. The single most important consequence:

A comment, a docstring, a wiki page, a code review checklist, or a line in CLAUDE.md saying "don't do X" is not a poka-yoke. It is training. Training degrades. A device does not. If your proposed fix relies on someone remembering something, keep going.

When to Use This Skill

• Use when the user says "poka-yoke this", "mistake-proof it", or "make this harder to get wrong".
• Use when designing an interface, schema or state machine and the ask is "make invalid states unrepresentable" or "so callers cannot screw it up".
• Use when auditing existing code for footguns: "what could bite us here", "what is easy to misuse".
• Use after an incident, when the fix must close the class rather than the case: "make sure this never happens again", "this is the third time".
• Especially for money, auth, permissions, deletion, migrations and pipelines, where failure is silent.

The two axes

Every real poka-yoke answers two questions. Use both when you classify a hazard or propose a device. They are the difference between this method and generic code review.

Axis 1, Regulatory function: what happens when the mistake occurs?

This is a strict preference ladder. Always reach for the highest rung you can afford.

Shingo's rule: prefer control over warning, always, and only settle for warning when control is genuinely too expensive, then say why out loud. In software the honest reason is usually "the language can't express it" or "it would break every existing caller," and both are worth stating explicitly so the tradeoff is visible.

Axis 2, Setting function: how does the device notice?

Shingo's three detection methods map cleanly onto software. These are your inspection lenses, run all three over any interface and you will find hazards that a general code review misses.

The third principle: inspect at the source

Shingo separated source inspection from informative inspection, which finds the defect

…