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.

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 only after it exists and comes in two forms. Ranked best first, that is three places you can put the device.

1. Source inspection: check the conditions before the error can occur. Designed in where you can, enforced at runtime where you cannot. The type, the constraint, the signature. 2. Self-check (informative): the work checks itself as it happens. Runtime. Assertions, fail-fast, validation at the boundary. 3. Successive check (informative): the next station checks the previous one. Review, CI, QA.

Push every device as far up this list as it will go. A CI gate that catches a bad migration is good; a schema that makes the bad migration unwritable is better and costs less forever.

How to use this skill

You have been asked to apply the method. There are two ways to do that, and picking the wrong one wastes the request.

If a specialist mode clearly fits the subject, load it: the table below maps them. Those files carry the domain detail this one does not: what a tenant-scoping device looks like, what expand/contract means, which lint rules catch silent failure.

If none clearly fits, apply the method here. This file is self-contained enough to do that, and refusing to act because the subject is not on a list would be its own failure. A Terraform module, a support runbook, a spreadsheet everyone edits, a release checklist, a prompt template, an onboarding process, a physical workflow: the method works on any of them, because Shingo developed it on an assembly line, for people fitting springs into switches, and not for software at all.

Applying it directly means four steps, in order:

1. Name what is being done, and by whom. A device protects a specific action taken by a specific person or system. "The pipeline" is not an action; "an engineer re-runs the deploy job after it fails halfway" is. 2. Run the three lenses over that action, can the wrong thing fit, can an incomplete or wrong-sized set pass, can the steps happen in the wrong order. Most subjects yield something on at least one. 3. For each hazard found, state it as a mistake someone could make, what happens when they do, whether it is silent, and what exists today to stop it. 4. Propose the highest-rung device you can afford, and say which rung it reaches. If you land on Warning, say what Control would have required and why you did not take it.

Then apply the two rules in How to talk about this below: name the mistake rather than the mistaken, and never let the answer come out as "be more careful" or "document it". Those are rung zero, and the whole method exists because they do not work.

If the request is bare, /poka-yoke with nothing attached, look at what is actually in front of you: the current diff, the file under discussion, the thing the conversation has been about. Say what you picked in one line before starting, so it is cheap to redirect you. If there is genuinely no subject, ask what they want mistake-proofed rather than guessing.

Choosing a mode

These are specialist modes, each carrying the full working method for its domain. Load one when it clearly fits. When two apply, do them in the order listed. When none does, apply the method directly as described above: the table is a shortcut, not a gate.

Two of these are easy to confuse. llm is for AI features you ship to users; agent-guardrails is for constraining an agent that works on your repo.

Modes compose, and real requests often need two. An incident involving a bad migration is retro for the analysis and ops for the device. A cross-tenant leak is retro plus authz. Read both; the retro decides what to install and the domain skill decides which device.

If the request is a general question ("what is poka-yoke", "how does this apply to software") answer from this file directly: the two axes above are the substance.

The hazard catalog and language specifics

The recurring ergonomic hazards: the signatures and shapes that reliably produce mistakes, live in ../../references/hazard-catalog.md, each with the lens that finds it and the device that fixes it. Read it when you are auditing or designing; it is the working vocabulary for both.

Language-specific devices (what the type system will and won't let you express, which constructs are idiomatic, what the linters can enforce) live in:

• ../../references/lang-typescript.md
• ../../references/lang-python.md
• ../../references/lang-rust-go.md

Read only the file for the language in front of you. If the language isn't covered, the two axes still apply, work out which construct in that language gives you contact, fixed-value, and motion-step checking, and say which rung you landed on.

How to talk about this

Two habits keep the analysis honest and keep people from getting defensive:

Name the mistake, not the mistaken. "This signature lets a caller swap the two IDs" is actionable and true. "The developer should have been more careful" is neither. Shingo was emphatic that blaming the operator is how organizations avoid fixing the process. Write findings about the code's affordances, never about who wrote it.

Say which rung you achieved, and what stopped you going higher. A recommendation that reads "added a runtime assertion (warning), control would need a newtype, which touches 40 call sites" gives the reader a real decision. One that reads "added validation" does not.

Applying changes

Propose before you edit. Show the hazard, the proposed device, and the rung it reaches, then wait for a go-ahead before changing files: the whole point of this method is that it changes the shape of an interface, and that is precisely the kind of change people want to see first. Once approved, apply it and leave a marker comment saying what mistake it prevents (see the recording section in audit).

The exception is when someone has explicitly asked you to write new code, in design mode, mistake-proofing is the code they asked for, so build it, then narrate which hazards you designed out and why.