poka-yoke

Detects mistake-prone code patterns and designs interfaces that make invalid states unrepresentable.

38.5k|4.9k|Updated Jun 11, 2025
One-click install
npx skills add https://github.com/github/awesome-copilot --skill poka-yoke
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: poka-yoke
Source: https://github.com/github/awesome-copilot/tree/main/skills/poka-yoke
Command: npx skills add https://github.com/github/awesome-copilot --skill poka-yoke

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Codebases are full of footguns: swappable same-type parameters, unbounded deletes, swallowed errors, and non-idempotent retries that let ordinary mistakes become production defects. This Skill audits code for these hazards and redesigns interfaces so the mistakes cannot be expressed at all, rather than relying on documentation or reviewer vigilance.

Core Features & Use Cases

  • Hazard Scanning: A bundled Python script (stdlib only) scans Python, TypeScript, Go, Rust, and SQL for 25+ hazard patterns across contact, fixed-value, and motion-step lenses, with diff, staged, and CI-friendly JSON modes.
  • Design Guidance: Applies parse-don't-validate, discriminated unions, branded types, typestate, and required idempotency keys so invalid states become compile errors.
  • Ranked Audit Output: Every finding is classified by what happens when the mistake occurs (Control, Warning, Detection) and named with the specific device that closes it.
  • Use Case: Before shipping a payments endpoint, run the scanner on the diff, then apply the reference guides to require an idempotency key backed by a unique constraint, so a retried charge cannot double-bill a customer.

Quick Start

Ask the AI to poka-yoke your current diff or audit a module for footguns, for example: review this pull request for ways callers could misuse it and rank each finding by severity.

Frequently Asked Questions about poka-yoke

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make invalid states unrepresentable in my API design?

Replace bags of optional fields with discriminated unions, parse unstructured input into proof-carrying types at the boundary, and give distinct concepts distinct types so swapped arguments fail to compile. The Skill walks through these moves with TypeScript, Python, Go, and Rust examples.

How do I scan a git diff for code footguns before committing?

Run scripts/detect_hazards.py with --staged for pre-commit checks, --diff for uncommitted changes, or --paths to scan directories. It supports --json for CI and exits non-zero when a scan covers zero files, so a typo cannot produce a false all-clear.

What languages does the hazard scanner support?

The scanner covers Python, TypeScript/JavaScript, Go, Rust, and SQL files. Python gets an additional AST-based pass for adjacent same-type parameters, assert-as-validation, and float equality comparisons that regexes cannot detect.

Does the scanner require installing any dependencies?

No. The scanner uses only the Python standard library and needs Python 3.9 or later, so it runs in CI pipelines and pre-commit hooks without an install step. Rules already covered by linters like ruff or eslint are off by default.

When should I not use mistake-proofing analysis?

Use a conventional code reviewer when you need a specific existing bug found, since this method targets the shapes that allow bug classes rather than the defect on the page. Also avoid over-fitting machinery to a one-off incident whose shape is unlikely to recur.