Proposal: explorable mode — why-demos, bite-cards, live playgrounds for rule-heavy content

[ZanziPanzi]

The gap

The skill is excellent at showing how a system is shaped (architecture, flowcharts, tables, slides). It has no first-class story for showing how a system behaves — its rules, failure modes, and validation logic. That content currently degrades into prose sections: paragraphs explaining why a rule exists, bullet lists of rules, screenshots of validators.

The proposal: three patterns, one mode

I've been running a local variant of this skill with an "explorable" mode built on three patterns (drawn from the explorable-explanations genre — Nicky Case et al.):

1. Why-demo — an interactive failure toggle over one dataset: the bad policy (what the code does today) must look attractive while lying; the good policy (the rule) looks worse but true. Replaces "why this rule exists" prose with a demonstration. Real example: a 12-run simulator where silent fallback-to-zero fabricates a 75% win-rate vs a fail-closed policy producing an honest 66.7% over 9 comparable runs and 3 structured blockers.
2. Bite-cards — one card per concept: the job in one sentence, the single most instructive rejection ("bites when…"), and a collapsed worked input → verdict example. Prose budget ≤ 2 sentences per section.
3. Live playground — a faithful JS port of the subject system's real validation logic (same rules, same message format, same check order), editable in-page with real fixtures. "See the machine before trusting it."

Guard rails that make or break it (equally part of the proposal):

• If a paragraph teaches better than a widget, write the paragraph — a toggle that demonstrates nothing is decoration.
• The playground must be a faithful port, never a paraphrase; fail closed on parse errors.
• Illustrative data must be labeled; no invented numbers presented as real.

Evidence it works

The patterns were proven on a real project's rulebook (8 contracts, a Python validator ported to JS in-page, all fixtures real documents) and the mode has produced consistently strong output since. The reference implementation is a single self-contained page — no CDNs, offline-openable, zero console errors — so it fits the skill's existing delivery model exactly.

Why an issue, not a PR

This adds a mode with opinions (prose budgets, fidelity-to-source rules), and it needs new reference + template files — a real design decision about skill scope, so I'd rather shape it with you than land a fait accompli. If there's interest, I can send a PR with the reference doc (explorable-patterns.md), a stripped starter template, and routing entries — everything is already written and battle-tested locally.

Curious whether this fits your direction for the skill, or whether you'd rather keep it plugin/extension territory.

[nicobailon]

Triaged during the backlog pass.

Disposition: keep open, blocked on owner product decision.

The idea is plausible and fits part of the skill's direction: rule-heavy explanations can benefit from why-demos, bite-cards, and page-local playgrounds. I do not think this should be accepted as an implementation PR yet because it would expand the supported public surface and possibly move the project toward owning validator fidelity, fixtures, security, and performance contracts.

The smallest acceptable path, if the maintainer wants it, is a docs/template-only slice: a routed explorable-patterns.md, a stripped full-mode starter template, and clear guardrails for source/provenance labels, safe fixed JS, no-JS fallback, accessibility, and credit to @ZanziPanzi. No new Pi/MCP action, quick schema, PPTX parity, shared validator runtime, or universal prose-budget rule.

A first-class mode needs a product contract first: trigger, page/slide scope, source-language parity, fixture format, failure semantics, browser/security/performance budgets, and MCP/API exposure.

I am leaving this open as a product decision rather than closing it as not planned.