Mistake-Proof Code Using Toyota Production System Principles

Poka-Yoke applies Shigeo Shingo's Toyota Production System mistake-proofing method to software design: instead of trying to make people more careful, it redesigns an interface so a mistake either cannot physically happen or announces itself immediately. It defines two classification axes. Axis 1 (Regulatory Function) is a four-rung preference ladder for what happens when a mistake occurs: Control (the mistake is impossible - a type that won't compile, a NOT NULL/CHECK/unique constraint, a required argument, a PreToolUse hook that denies, a protected branch), Warning (the mistake is possible but announced the moment it happens - a lint error, a failing CI gate, a runtime assertion, a confirmation prompt naming the exact thing being destroyed), Detection (the mistake ships and something finds it afterward - tests, monitoring, alerting, reconciliation), and rung 0, which is explicitly not a poka-yoke at all - documentation, comments, training, or a code-review checklist, because those rely on a human remembering and "training degrades, a device does not." Axis 2 (Setting Function) gives three inspection lenses to run over any interface: Contact ("can the wrong thing fit?" - distinct types instead of shared primitives, branded/newtype IDs, parse-don't-validate at boundaries, discriminated unions), Fixed-value ("can the wrong count or an incomplete set pass?" - exhaustive match/switch over an enum, required fields, row-count guards, checksums, config validated as a whole at boot), and Motion-step ("can the steps happen in the wrong order or be skipped?" - typestate, a builder that can't .build() until required steps run, state machines with illegal transitions unrepresentable, idempotency keys, transactions). A third principle ranks where to place the device: source inspection (check the conditions before the error can occur - the type, the constraint, the signature) beats self-check (the work validates itself at runtime) beats successive check (the next station, i.e. review/CI/QA, catches the previous one's mistake) - "a CI gate that catches a bad migration is good; a schema that makes the bad migration unwritable is better and costs less forever." Applying the method is a fixed four-step process: name the specific action and actor being protected (not "the pipeline" but "an engineer re-runs the deploy job after it fails halfway"); run all three lenses over that action; for each hazard found, state it as a concrete mistake, what happens when it occurs, whether it's silent, and what exists today to stop it; and propose the highest-rung device affordable, explicitly naming which rung it reaches and, if it lands on Warning rather than Control, why Control wasn't taken. A worked example walks a deleteAccount(accountId, tenantId) API through the full method - identifying that the two same-shaped string IDs can be swapped, proposing distinct validated ID types as the Control device, a boundary ownership check as the Warning fallback if that's not possible, and audit logging/reconciliation as Detection, explicitly not to be presented as the poka-yoke itself.

Use it when a user asks to "poka-yoke this," "mistake-proof it," or "make this harder to get wrong," when designing an interface/schema/state machine to make invalid states unrepresentable, when auditing existing code for footguns, or after an incident where the fix needs to close the whole class of mistake rather than just the one instance - especially for money, auth, permissions, deletion, migrations, and pipelines, where failure is silent. Do NOT accept a fix that relies on someone remembering something (a comment, a docstring, a wiki page, or a CLAUDE.md line saying "don't do X") as a poka-yoke - the skill is explicit that this is training, not a device, and training degrades while a device does not. Do NOT treat the method as proof a design is correct: its own limitations state it reduces predictable misuse but cannot cover hazards the analysis never identified, a guard can itself be wrong or overbroad, and it complements but never replaces domain review, security review, testing, and observability.

Input is a specific interface, schema, state machine, or workflow under discussion - the current diff, a Terraform module, a runbook, a release checklist - or, on a bare /poka-yoke invocation, whatever is currently in front of the conversation (stated in one line before starting). Output is a hazard-by-hazard analysis (the mistake, its silence, and the specific action/actor it protects), a proposed device rated by rung (Control/Warning/Detection), and - only after the hazard and proposed device are shown and approved - the actual code change implementing it, with the prevented mistake recorded for future maintainers.

A prompting-only methodology skill with no external tools or APIs; it applies directly to whatever code, config, or process is under discussion.

Engineers designing an interface, schema, or state machine - or auditing existing code after an incident - who want a disciplined, Shingo-derived framework for making mistakes structurally impossible or immediately visible, rather than a code-review comment asking people to be more careful.