Index of every page on this site: llms.txt
All skills
Run it yourself

Turn a bug, outage or repeated mistake into a device that makes the whole class impossible. Use when something already broke: "make sure this never happens again", "this is the third time", "postmortem", "how did this get through". Root-causes to the missing constraint, then sweeps every other site where the mistake is still available. For a pipeline use data, a deploy use ops, cross-tenant use authz, an AI feature use llm.

Use this Skill: https://skilld.dev/gh/rainmanjam/poka-yoke/retro

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈109 tokens for metadata: the name and description. ≈1.7k when used: this file.

Description uses 5.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈435 characters, or 5.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Poka-Yoke Retro

A defect got out. The fix for the defect is the easy part and is usually already done or obvious. This mode is about the harder and more valuable question: what made the mistake available, and what device removes it for good?

Shingo's framing is the whole method here. Do not ask why the person erred, people err, that is a constant. Ask why the process permitted the error to become a defect, and what would have physically stopped it.

1. Separate the three things

People conflate these, and conflating them is why incidents repeat.

  • The defect: what the user or system experienced. "Customers were charged twice."
  • The mistake: the specific human action that produced it. "The retry path called charge() again without an idempotency key."
  • The hazard: the property of the system that made that mistake possible and silent. "charge() accepts an optional idempotency key and succeeds without one."

Fixing the defect ships today. Fixing the mistake helps one code path. Only fixing the hazard prevents recurrence, and the hazard is almost always a missing constraint, not a missing piece of knowledge.

Write all three out explicitly before proposing anything. If you cannot state the hazard as a property of the system, you have not found it yet.

2. Ask why until you reach a constraint

Run the whys, with one discipline: an acceptable terminal answer is a missing constraint, never a missing human quality. If a chain ends in "they forgot," "they didn't know," "they were rushing," or "it wasn't documented," you stopped one step early, keep going and ask why forgetting was possible, why the knowledge was needed at all, why the system accepted the result.

Double charge → retry called charge() twice → the retry path didn't pass an idempotency key → the key is an optional parameter → why is it optional? → it was added later and made optional to avoid breaking callers → there is no compile-time or database-level requirement that a charge be idempotent.

That last line is the hazard, and it is fixable: make the parameter required, or add a unique constraint on (account_id, idempotency_key). Compare it to "the engineer should have passed the key," which is fixable only by hiring different humans.

Also ask the escape question separately: what should have caught this and didn't? Usually there was a device: a test, a review, a type, and it was absent, disabled, or too weak. That gap is a second finding in its own right.

3. Sweep for the class. This is the step that gets skipped

A poka-yoke that fixes one call site is not a poka-yoke. Before proposing anything, find every other place the same mistake is still available. This is almost always where the real value of a retro sits, and it is the step people omit under time pressure.

Search by the shape of the hazard, not by the text of the bug:

  • Every other caller of the same function or endpoint.
  • Every other function with the same dangerous signature shape, other optional-when-it-should- be-required parameters, other same-type adjacent arguments, other unguarded bulk operations.
  • The same pattern in sibling services, other languages in the monorepo, scripts, jobs, and infrastructure code.
  • Run python3 ../../scripts/detect_hazards.py --paths <repo> --id <hazard-id>: the ID is the one printed with each finding, to catch instances you would not have thought to grep for.

Report the count plainly: "the same hazard exists at 6 other call sites" changes the conversation about how much the fix is worth.

4. Choose the device by rung

Now propose, using the ladder from the router skill. For an incident that already cost something real, push hard for Control: you have the strongest evidence you will ever have that this mistake happens.

Rung For this incident, that would mean
Control Required parameter · database unique constraint · type that cannot represent the bad state · CI check that cannot be merged past
Warning Lint rule · runtime assertion · alert at the moment of the action
Detection Regression test · monitor · reconciliation job
None "Added a note to the runbook" · "reminded the team" · "added a review checklist item"

A regression test is genuinely valuable and you should write one. It proves the fix and stops this exact path regressing. But be honest that it is rung 3: it catches the mistake after someone makes it, and only on the path you thought of. If the retro produces only a test, say so, and say what a Control-rung device would have required.

Beware the fix that is really rung zero wearing a costume: more documentation, a new checklist item, a Slack reminder, a training session, an extra required reviewer. These feel like action and change nothing. If that is genuinely all that is possible, name it as an accepted risk rather than a resolution.

5. Write it up

# Retro · <short title> · <YYYY-MM-DD>

**Defect**: <what was experienced, with blast radius: how many, how much, how long>
**Mistake**: <the specific action taken>
**Hazard**: <the system property that made it possible and quiet>

## Why it was possible
<the chain, ending at a missing constraint>

## Why nothing caught it
<the device that should have existed, was disabled, or was too weak>

## Class sweep
<n other sites where this mistake is still available, list them>

## Devices
| Device | Rung | Covers | Status |
|---|---|---|---|
| <change> | Control | all N sites | proposed |
| <regression test> | Detection | the original path | done |

## Accepted risk
<what remains possible, and why that is acceptable>

Save to docs/poka-yoke/retro-YYYY-MM-DD-<slug>.md, and put a poka-yoke: marker comment at each installed device naming the mistake it prevents. That is what stops a future engineer removing it as dead weight, since by then it will never have fired. See the recording section in audit; do not ask anyone to hand-maintain a registry file.

6. Verify the device before you close it

Prove the fix. Reproduce the original mistake against the new device and show it being refused, then show the correct path still working. A device that was never observed to fire is a belief, not a control, and after an incident, a false sense of protection is the most expensive thing you can ship.

Tone

Write about the system, never the person. Not because it is polite, but because it is more accurate and it is the only version that produces a fix: "the engineer should have been more careful" has no implementation. Shingo's argument was that blaming the operator is precisely how organizations avoid improving the process. Names belong in the timeline if at all; the analysis is about affordances.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides a structured methodology for performing root-cause analysis after software failures. It focuses on identifying systemic hazards and implementing 'Poka-Yoke' (error-proofing) devices. It utilizes a local helper script to automate the identification of similar defects across a codebase.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 726a575. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Activeupdated 3 months ago

README badge

README badge for rainmanjam/poka-yoke/retro