audit

Poka-Yoke

An agent will tell you what to fix. It will rarely tell you what its fix makes impossible.

Unprompted, models close a design by naming what it forecloses 45% of the time. With these skills, 80%, measured across 132 graded verdicts and six model families. That one habit is most of what this does, and it is the difference between advice you agree with and a constraint you can rely on.

The average conceals where the effect lives. Asked squarely to design an interface, models already do this 77% of the time unprompted and the skills add eleven points. The large gains are in the scenarios where nobody asked for a design review — see the table below.

A dependency-free hazard scanner for TypeScript, Python, Go, Rust and SQL; installable pre-commit / CI / lint / hook devices; and 11 skills that apply the same method while you design. Shigeo Shingo's method, applied to code, process, interfaces, infrastructure, and AI.

Runs on 19 agent runtimes from one set of skills, 10 with a native manifest. Benchmarked on Claude Code; the support tiers are stated honestly.

[!NOTE] 591 blind-graded runs across six runtimes, at the first turn of a fresh session, scored against pre-written assertions by a grader that never sees which configuration produced a response. Every model improves on a no-skill baseline by more than noise: Fable 5 +8.3 pp, Opus 5 +3.6 pp, Sonnet 5 +8.6 pp, Haiku 4.5 +12.9 pp: all four 95% intervals exclude zero. Nine of the 52 cells came out negative, where chance alone would produce about 18: individual cells hold 1 to 7 runs and are too small to read on their own, so the scarcity of regressions is the signal rather than their existence. See the numbers.

All 591 runs are verified against the scenario prompts as they stand in this commit.

What this does not yet establish. Blind grading controls bias, not accuracy. The baseline is no skill, not a different methodology, so whether any structured method in context would do the same is untested; a control arm is designed and unrun. And every run is a first turn, which measures the ceiling rather than what survives an afternoon of accumulated context. The full list of what the numbers cannot tell you.

Contents

• What it trades, read this before installing
• Install · Requirements · Other runtimes · Updating and uninstalling
• The hazard detector, the part that does not decay
• What's inside, 11 skills, starting with design
• The method: the two axes that do the work
• What it looks like · Invocation
• Benchmarks · Caveats · Repo layout · Prior art
• Contributing · Releasing · Changelog · Code of conduct · License

---

What it trades

Loading a method changes what a model attends to, and attention is finite. Measured across the same 591 runs, the skills make responses markedly more constructive and slightly worse at noticing the specific defect already in front of them:

Where that one behaviour is measured, broken out. The family mean above averages a task where models already do it with three where they largely do not, which flatters the easy case and buries the interesting one:

The skills matter most when nobody asked for a design review. | Notes pre-commit is bypassable and must be backed by CI | 35% | 92% | | Identifies a raw SQL interpolation as an injection vector | 92% | 69% | | Explains why a silently wrong number beats a failed pipeline | 54% | 31% |

So: if you want the bug in front of you found, use a reviewer. If you want the shape changed so that class of bug stops being expressible, use this. Loading it for the first job makes the model measurably worse at it. That trade is the product, not a caveat about it.

---

People will always make mistakes. That is not the problem worth solving: the problem is letting a mistake become a defect.

Shigeo Shingo: the industrial engineer who named poka-yoke and worked it out on the factory floor, built his quality method on that distinction. Instead of asking workers to be more careful, he redesigned the work so a mistake could not survive it. Assemblers kept forgetting a spring inside a switch, so he had them lay both springs in a dish first: a spring still in the dish was the error announcing itself, before the unit could move on.

This plugin applies that method to software. Not as a metaphor: the taxonomy is the actual working tool. Every finding is classified by what happens when the mistake occurs and how the device notices, which is what keeps it from collapsing into generic code review.

The line that does most of the work:

A comment, a docstring, a wiki page, a review checklist, or a line in CLAUDE.md 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.

You have already tried writing the rule down. Every repository that needs this has a CLAUDE.md, an AGENTS.md or a CONTRIBUTING.md with a list of things everyone is supposed to remember, and the list is longer than it was a year ago because the reminders did not hold. That list is the real alternative to this plugin, not an unassisted model, and the argument here is about why it decays and what to put in its place.

That is also the honest limit o