poka-yoke: Instructions file for Claude Code

Contributing to poka-yoke: guidance for agents and people

This repository argues that instructions degrade and devices do not. It has to hold itself to that, so read this before changing anything here.

The one rule that governs the rest

If your change relies on someone remembering something, it is not finished.

A comment, a checklist item, a line in this file: those are training. Training degrades. When you fix something here, ask what device would have caught it, and add that too. Every check under .github/workflows/validate.yml exists because something drifted silently first.

Verify the instrument before you trust it

The recurring failure in this project is not broken code. It is a check that cannot fail. Every one of these looked like a passing test:

• The detector reported {"count": 0} for a clean scan and for scanning nothing at all.
• The description optimizer failed its own positive control, so its numbers were void.
• A thumbnail scorer returned byte-identical floats for different images.
• A beat checker watched opacity while the thing it measured was still moving.

So when you add a check, prove it fails. Break the thing on purpose, watch the check catch it, put it back. A check that has never once gone red is a rumour, not a device.

Two shapes recur often enough to name. A probe keyed to prose stops probing when the prose changes. A README figure check that matched **N% → M%** silently verified nothing after a rewrite moved the numbers out of bold, and passed while checking zero claims. Assert that the probe found something before asserting the something is correct. And absent data does not raise. A failed run leaves an empty directory, a missing grading just shrinks a cell, and a narrowed aggregate simply reports fewer columns. Each looks like the shape of the matrix rather than like an error, so make missing input fail loudly instead of averaging what remains.

The baseline arm is no skill, which is not the comparison a reader faces: theirs is against the rules file they already wrote. with_placebo (a matched but unrelated methodology) and with_defensive (the method this project argues against) exist to close that gap. Until they have run, no result here distinguishes "this method works" from "any methodology in context works", and a write-up that implies otherwise is overclaiming.