Add poka-yoke skill: make misuse unrepresentable rather than warned against (#2792)

* Add poka-yoke skill: make misuse unrepresentable rather than warned against Mistake-proofing, applied to code. The skill pushes toward devices that make a wrong action impossible or self-announcing, rather than instructions asking someone to avoid it, and refuses to accept a comment or a convention as a fix. The gap it addresses. Given a design, models readily list what to fix and rarely state what the fix makes impossible. Measured across 591 blind-graded runs and six model families, responses named the foreclosed set 42% of the time unprompted and 81% with this skill applied. Assertions were written before the runs and graded blind to configuration. Stated with its limits, because they matter: every run was the first turn of a fresh session, so this measures the ceiling rather than what survives a long working session; the comparison was against no methodology rather than a different one, so it does not establish that this particular method caused the gain; and the skill costs something measurable, making responses somewhat worse at spotting the specific defect already on the page while better at changing the shape that allowed it. All of that is in the skill body rather than omitted. Bundled, all self-contained, no network access and no dependencies: scripts/detect_hazards.py standard-library scanner, 42 pattern rules across 20 hazard shapes, five languages references/hazard-catalog.md the taxonomy with device per shape references/lang-*.md Python, TypeScript, Go and Rust patterns Verified with npm run skill:validate and npm run build. Raw benchmark runs, the harness and the assertion checklists are public at https://github.com/rainmanjam/poka-yoke * Rename HasTable to HasFrom in the TypeScript typestate example codespell failed the PR: it reads HasTable as a misspelling of hashtable. The identifier is a legitimate generic parameter on a typestate builder, QueryBuilder<HasTable, HasWhere>, so this is a false positive, but it is our file breaking their gate and the fix costs nothing. HasFrom is also the better name: the flag tracks whether .from() has been called, not whether a table exists. Renamed in the upstream repository too, so the two copies do not diverge on day one. Verified the whole bundle is codespell-clean locally. * Correct the effect figures in the poka-yoke skill The submitted numbers (42% -> 81%) could not be reproduced from the upstream gradings. Recomputed over the six models the sentence describes: 45% -> 80% across 132 verdicts. Adds the per-scenario breakdown, which is the more useful claim: the gains are in tasks where nobody asked for a design review.
2026-08-26 18:45:12 +00:00 · 2026-08-26 09:56:32 +10:00
parent bb4735f075
commit 7c36d87f82
7 changed files with 1736 additions and 0 deletions
@@ -312,6 +312,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [playwright-automation-fill-in-form](../skills/playwright-automation-fill-in-form/SKILL.md)<br />`gh skills install github/awesome-copilot playwright-automation-fill-in-form` | Automate filling in a form using Playwright MCP | None |
 | [playwright-explore-website](../skills/playwright-explore-website/SKILL.md)<br />`gh skills install github/awesome-copilot playwright-explore-website` | Website exploration for testing using Playwright MCP | None |
 | [playwright-generate-test](../skills/playwright-generate-test/SKILL.md)<br />`gh skills install github/awesome-copilot playwright-generate-test` | Generate a Playwright test based on a scenario using Playwright MCP | None |
+| [poka-yoke](../skills/poka-yoke/SKILL.md)<br />`gh skills install github/awesome-copilot poka-yoke` | Mistake-proof code so misuse cannot be expressed, rather than warning against it. Use when designing an interface, schema, or state machine and the user wants it hard to get wrong ("make invalid states unrepresentable", "so callers cannot screw it up", "type-safe API", "pit of success"); when auditing existing code for footguns ("what could bite us here", "what is easy to misuse", "poka-yoke this repo", "review this diff for ways to get it wrong"); or when a bug has recurred and the fix must close the class rather than the case ("make sure this never happens again", "this is the third time"). Especially for money, auth, permissions, deletion, migrations, and pipelines where failure is silent. Classifies every finding by what happens when the mistake occurs and how the device notices, which is what keeps it from collapsing into generic code review. | `references/hazard-catalog.md`<br />`references/lang-python.md`<br />`references/lang-rust-go.md`<br />`references/lang-typescript.md`<br />`scripts/detect_hazards.py` |
 | [postgresql-code-review](../skills/postgresql-code-review/SKILL.md)<br />`gh skills install github/awesome-copilot postgresql-code-review` | PostgreSQL-specific code review assistant focusing on PostgreSQL best practices, anti-patterns, and unique quality standards. Covers JSONB operations, array usage, custom types, schema design, function optimization, and PostgreSQL-exclusive security features like Row Level Security (RLS). | None |
 | [postgresql-optimization](../skills/postgresql-optimization/SKILL.md)<br />`gh skills install github/awesome-copilot postgresql-optimization` | PostgreSQL-specific development assistant focusing on unique PostgreSQL features, advanced data types, and PostgreSQL-exclusive capabilities. Covers JSONB operations, array types, custom types, range/geometric types, full-text search, window functions, and PostgreSQL extensions ecosystem. | None |
 | [power-apps-code-app-scaffold](../skills/power-apps-code-app-scaffold/SKILL.md)<br />`gh skills install github/awesome-copilot power-apps-code-app-scaffold` | Scaffold a complete Power Apps Code App project with PAC CLI setup, SDK integration, and connector configuration | None |