poka-yoke
Mistake-proofing for anything: code, config, a schema, a process, a runbook, a form. Use when someone says "poka-yoke this", "mistake-proof it", "make this harder to get wrong", or runs /poka-yoke with no mode named. Applies Shigeo Shingo's method directly to any subject, and hands off to a specialist mode when one clearly fits. Start here when no other poka-yoke mode obviously applies.
rainmanjam · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rainmanjam/poka-yoke --skill poka-yoke技能说明
name: poka-yoke description: >- Mistake-proofing for anything: code, config, a schema, a process, a runbook, a form. Use when someone says "poka-yoke this", "mistake-proof it", "make this harder to get wrong", or runs /poka-yoke with no mode named. Applies Shigeo Shingo's method directly to any subject, and hands off to a specialist mode when one clearly fits. Start here when no other poka-yoke mode obviously applies.
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.
| Rung | Name | What it does | Software examples |
|---|---|---|---|
| 1 | Control | The mistake is impossible. The work cannot proceed. | Type won't compile · NOT NULL / CHECK / unique constraint · required function argument · private constructor + smart constructor · PreToolUse hook returns deny · protected branch |
| 2 | Warning | The mistake is possible but announced at the moment it happens. | Lint error in the editor · failing CI gate · runtime assertion that throws · confirmation prompt naming the exact thing being destroyed |
| 3 | Detection | The mistake ships, and something finds it afterward. | Tests · monitoring · alerting · reconciliation job |
| 0 | (not a poka-yoke) | Relies on a human remembering. | Docs · comments · training · "be careful" · review checklists |
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.
| Method | Factory floor | The question to ask code | Software devices |
|---|---|---|---|
| Contact | The part physically won't seat unless it's the right shape and orientation | Can the wrong thing fit? | Distinct types instead of shared primitives · branded/newtype IDs · parse-don't-validate at boundaries · units in the type · discriminated unions instead of bags of optionals |
| Fixed-value | A counter says all 6 screws were fitted | Can the wrong count or an incomplete set pass? | Exhaustive match/switch over an enum · required fields · "all migrations applied" check · row-count guard on a bulk write · checksums · config validated as a whole at boot |
| Motion-step | A sensor confirms step 3 happened before step 4 | Can the steps happen in the wrong order, or be skipped? | Typestate · builder that cannot .build() until required steps run · state machines with illegal transitions unrepresentable · idempotency keys · RAII / defer / context managers · transactions |
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.
- 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.
- Self-check (informative): the work checks itself as it happens. Runtime. Assertions, fail-fast, validation at the boundary.
- 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:
- Name what is being done, and by whom. A device protects a specific action taken by a specific person or system.