@iowarp/clio-coder 0.3.0 → 0.3.2

package/skills/coding/ast-grep/references/rule_reference.md

@@ -0,0 +1,297 @@
+# ast-grep Rule Reference
+
+This document provides comprehensive documentation for ast-grep rule syntax, covering all rule types and metavariables.
+
+## Introduction to ast-grep Rules
+
+ast-grep rules are declarative specifications for matching and filtering Abstract Syntax Tree (AST) nodes. They enable structural code search and analysis by defining conditions an AST node must meet to be matched.
+
+### Rule Categories
+
+ast-grep rules are categorized into three types:
+
+* **Atomic Rules**: Match individual AST nodes based on intrinsic properties like code patterns (`pattern`), node type (`kind`), or text content (`regex`).
+* **Relational Rules**: Define conditions based on a target node's position or relationship to other nodes (e.g., `inside`, `has`, `precedes`, `follows`).
+* **Composite Rules**: Combine other rules using logical operations (AND, OR, NOT) to form complex matching criteria (e.g., `all`, `any`, `not`, `matches`).
+
+## Anatomy of an ast-grep Rule Object
+
+The ast-grep rule object is the core configuration unit defining how ast-grep identifies and filters AST nodes. It's typically written in YAML format.
+
+### General Structure
+
+Every field within an ast-grep Rule Object is optional, but at least one "positive" key (e.g., `kind`, `pattern`) must be present.
+
+A node matches a rule if it satisfies all fields defined within that rule object, implying an implicit logical AND operation.
+
+For rules using metavariables that depend on prior matching, explicit `all` composite rules are recommended to guarantee execution order.
+
+### Rule Object Properties
+
+| Property | Type | Category | Purpose | Example |
+| :--- | :--- | :--- | :--- | :--- |
+| `pattern` | String or Object | Atomic | Matches AST node by code pattern. | `pattern: console.log($ARG)` |
+| `kind` | String | Atomic | Matches AST node by its kind name. | `kind: call_expression` |
+| `regex` | String | Atomic | Matches node's text by Rust regex. | `regex: ^[a-z]+$` |
+| `nthChild` | number, string, Object | Atomic | Matches nodes by their index within parent's children. | `nthChild: 1` |
+| `range` | RangeObject | Atomic | Matches node by character-based start/end positions. | `range: { start: { line: 0, column: 0 }, end: { line: 0, column: 10 } }` |
+| `inside` | Object | Relational | Target node must be inside node matching sub-rule. | `inside: { pattern: class $C { $$$ }, stopBy: end }` |
+| `has` | Object | Relational | Target node must have descendant matching sub-rule. | `has: { pattern: await $EXPR, stopBy: end }` |
+| `precedes` | Object | Relational | Target node must appear before node matching sub-rule. | `precedes: { pattern: return $VAL }` |
+| `follows` | Object | Relational | Target node must appear after node matching sub-rule. | `follows: { pattern: import $M from '$P' }` |
+| `all` | Array<Rule> | Composite | Matches if all sub-rules match. | `all: [ { kind: call_expression }, { pattern: foo($A) } ]` |
+| `any` | Array<Rule> | Composite | Matches if any sub-rules match. | `any: [ { pattern: foo() }, { pattern: bar() } ]` |
+| `not` | Object | Composite | Matches if sub-rule does not match. | `not: { pattern: console.log($ARG) }` |
+| `matches` | String | Composite | Matches if predefined utility rule matches. | `matches: my-utility-rule-id` |
+
+## Atomic Rules
+
+Atomic rules match individual AST nodes based on their intrinsic properties.
+
+### pattern: String and Object Forms
+
+The `pattern` rule matches a single AST node based on a code pattern.
+
+**String Pattern**: Directly matches using ast-grep's pattern syntax with metavariables.
+
+```yaml
+pattern: console.log($ARG)
+```
+
+**Object Pattern**: Offers granular control for ambiguous patterns or specific contexts.
+
+* `selector`: Pinpoints a specific part of the parsed pattern to match.
+  ```yaml
+  pattern:
+    selector: field_definition
+    context: class { $F }
+  ```
+
+* `context`: Provides surrounding code context for correct parsing.
+
+* `strictness`: Modifies the pattern's matching algorithm (`cst`, `smart`, `ast`, `relaxed`, `signature`).
+  ```yaml
+  pattern:
+    context: foo($BAR)
+    strictness: relaxed
+  ```
+
+### kind: Matching by Node Type
+
+The `kind` rule matches an AST node by its `tree_sitter_node_kind` name, derived from the language's Tree-sitter grammar. Useful for targeting constructs like `call_expression` or `function_declaration`.
+
+```yaml
+kind: call_expression
+```
+
+### regex: Text-Based Node Matching
+
+The `regex` rule matches the entire text content of an AST node using a Rust regular expression. It's not a "positive" rule, meaning it matches any node whose text satisfies the regex, regardless of its structural kind.
+
+### nthChild: Positional Node Matching
+
+The `nthChild` rule finds nodes by their 1-based index within their parent's children list, counting only named nodes by default.
+
+* `number`: Matches the exact nth child. Example: `nthChild: 1`
+* `string`: Matches positions using An+B formula. Example: `2n+1`
+* `Object`: Provides granular control:
+  * `position`: `number` or An+B string.
+  * `reverse`: `true` to count from the end.
+  * `ofRule`: An ast-grep rule to filter the sibling list before counting.
+
+### range: Position-Based Node Matching
+
+The `range` rule matches an AST node based on its character-based start and end positions. A `RangeObject` defines `start` and `end` fields, each with 0-based `line` and `column`. `start` is inclusive, `end` is exclusive.
+
+## Relational Rules
+
+Relational rules filter targets based on their position relative to other AST nodes. They can include `stopBy` and `field` options.
+
+### inside: Matching Within a Parent Node
+
+Requires the target node to be inside another node matching the `inside` sub-rule.
+
+```yaml
+inside:
+  pattern: class $C { $$$ }
+  stopBy: end
+```
+
+### has: Matching with a Descendant Node
+
+Requires the target node to have a descendant node matching the `has` sub-rule.
+
+```yaml
+has:
+  pattern: await $EXPR
+  stopBy: end
+```
+
+### precedes and follows: Sequential Node Matching
+
+* `precedes`: Target node must appear before a node matching the `precedes` sub-rule.
+* `follows`: Target node must appear after a node matching the `follows` sub-rule.
+
+Both include `stopBy` but not `field`.
+
+### stopBy and field: Refining Relational Searches
+
+**stopBy**: Controls search termination for relational rules.
+
+* `"neighbor"` (default): Stops when immediate surrounding node doesn't match.
+* `"end"`: Searches to the end of the direction (root for `inside`, leaf for `has`).
+* `Rule object`: Stops when a surrounding node matches the provided rule (inclusive).
+
+**field**: Specifies a sub-node within the target node that should match the relational rule. Only for `inside` and `has`.
+
+**Best Practice**: When unsure, always use `stopBy: end` to ensure the search goes to the end of the direction.
+
+## Composite Rules
+
+Composite rules combine atomic and relational rules using logical operations.
+
+### all: Conjunction (AND) of Rules
+
+Matches a node only if all sub-rules in the list match. Guarantees order of rule matching, important for metavariables.
+
+```yaml
+all:
+  - kind: call_expression
+  - pattern: console.log($ARG)
+```
+
+### any: Disjunction (OR) of Rules
+
+Matches a node if any sub-rules in the list match.
+
+```yaml
+any:
+  - pattern: console.log($ARG)
+  - pattern: console.warn($ARG)
+  - pattern: console.error($ARG)
+```
+
+### not: Negation (NOT) of a Rule
+
+Matches a node if the single sub-rule does not match.
+
+```yaml
+not:
+  pattern: console.log($ARG)
+```
+
+### matches: Rule Reuse and Utility Rules
+
+Takes a rule-id string, matching if the referenced utility rule matches. Enables rule reuse and recursive rules.
+
+## Metavariables
+
+Metavariables are placeholders in patterns to match dynamic content in the AST.
+
+### $VAR: Single Named Node Capture
+
+Captures a single named node in the AST.
+
+* **Valid**: `$META`, `$META_VAR`, `$_`
+* **Invalid**: `$invalid`, `$123`, `$KEBAB-CASE`
+* **Example**: `console.log($GREETING)` matches `console.log('Hello World')`.
+* **Reuse**: `$A == $A` matches `a == a` but not `a == b`.
+
+### $$VAR: Single Unnamed Node Capture
+
+Captures a single unnamed node (e.g., operators, punctuation).
+
+**Example**: To match the operator in `a + b`, use `$$OP`.
+
+```yaml
+rule:
+  kind: binary_expression
+  has:
+    field: operator
+    pattern: $$OP
+```
+
+### $$$MULTI_META_VARIABLE: Multi-Node Capture
+
+Matches zero or more AST nodes (non-greedy). Useful for variable numbers of arguments or statements.
+
+* **Example**: `console.log($$$)` matches `console.log()`, `console.log('hello')`, and `console.log('debug:', key, value)`.
+* **Example**: `function $FUNC($$$ARGS) { $$$ }` matches functions with varying parameters/statements.
+
+### Non-Capturing Metavariables (_VAR)
+
+Metavariables starting with an underscore (`_`) are not captured. They can match different content even if named identically, optimizing performance.
+
+* **Example**: `$_FUNC($_FUNC)` matches `test(a)` and `testFunc(1 + 1)`.
+
+### Important Considerations for Metavariable Detection
+
+* **Syntax Matching**: Only exact metavariable syntax (e.g., `$A`, `$$B`, `$$$C`) is recognized.
+* **Exclusive Content**: Metavariable text must be the only text within an AST node.
+* **Non-working**: `obj.on$EVENT`, `"Hello $WORLD"`, `a $OP b`, `$jq`.
+
+The ast-grep playground is useful for debugging patterns and visualizing metavariables.
+
+## Common Patterns and Examples
+
+### Finding Functions with Specific Content
+
+Find functions that contain await expressions:
+
+```yaml
+rule:
+  kind: function_declaration
+  has:
+    pattern: await $EXPR
+    stopBy: end
+```
+
+### Finding Code Inside Specific Contexts
+
+Find console.log calls inside class methods:
+
+```yaml
+rule:
+  pattern: console.log($$$)
+  inside:
+    kind: method_definition
+    stopBy: end
+```
+
+### Combining Multiple Conditions
+
+Find async functions that use await but don't have try-catch:
+
+```yaml
+rule:
+  all:
+    - kind: function_declaration
+    - has:
+        pattern: await $EXPR
+        stopBy: end
+    - not:
+        has:
+          pattern: try { $$$ } catch ($E) { $$$ }
+          stopBy: end
+```
+
+### Matching Multiple Alternatives
+
+Find any type of console method call:
+
+```yaml
+rule:
+  any:
+    - pattern: console.log($$$)
+    - pattern: console.warn($$$)
+    - pattern: console.error($$$)
+    - pattern: console.debug($$$)
+```
+
+## Troubleshooting Tips
+
+1. **Rule doesn't match**: Use `dump_syntax_tree` to see the actual AST structure
+2. **Relational rule issues**: Ensure `stopBy: end` is set for deep searches
+3. **Wrong node kind**: Check the language's Tree-sitter grammar for correct kind names
+4. **Metavariable not working**: Ensure it's the only content in its AST node
+5. **Pattern too complex**: Break it down into simpler sub-rules using `all`

package/skills/coding/coding-standards/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: coding-standards
+description: "Use when writing or refactoring TypeScript and the project has not pinned its own conflicting standards — new modules, error-handling design, schema parsing, module boundaries — or when another skill needs a TypeScript standards reference. Correct-by-construction rules: errors as values, parse don't validate, illegal states unrepresentable, deep modules, functional core / imperative shell."
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/coding-standards
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/dmmulroy/skills/tree/main/coding-standards
+  eval-status: smoke-checked
+  model-size: any
+  provisional: true
+  agents:
+    - main
+    - coder
+---
+
+# Coding Standards (TypeScript, correct-by-construction)
+
+Reference, not a workflow. Apply to new and refactored code. When rules
+pull in different directions: correctness and debuggability first, then
+these standards, then compatible project conventions; contain incompatible
+existing patterns at the nearest boundary instead of copying them into new
+code, and never rewrite unrelated old code without an explicit migration
+request. **The host project's own documented standards always win over
+this file.**
+
+## Errors
+
+- Expected failures are values in the return type, as custom tagged
+  errors; callers handle or return them upward, and the outermost boundary
+  translates them (HTTP response, exit code, retry decision). Use the
+  repo's established result mechanism; absent one, a small local tagged
+  union `{_tag: "ok"|"err", ...}` suffices.
+- Promise rejection is throwing. Catch unclassified third-party rejections
+  inside the owning adapter and translate before they cross its boundary.
+- Throw only for defects: violated invariants, impossible branches,
+  not-yet-implemented paths. A missing config value is an expected startup
+  failure, not a defect.
+- Custom errors carry: a stable `_tag` (`as const`), a useful message,
+  structured context fields, optional `cause: unknown`. Keep error unions
+  precise at module boundaries; broad `AppError` types belong only near
+  entrypoints and rendering.
+
+## Parse, don't validate
+
+- Boundary code turns `unknown` input into domain types before it enters
+  inner code; inner code never re-checks what a parser proved.
+- `parseX(input): Result<X, ParseXError>` for untrusted input; `makeX` for
+  smart construction from typed pieces; `isX` for predicates. A function
+  returning a refined value is a parser — do not name it `validateX`.
+- Schema libraries are boundary parsers, not validators sprinkled through
+  core logic; use the repo's established one. Never pass a schema-inferred
+  transport shape through the application.
+- Brand types where a mix-up is realistic: IDs (`UserId` vs `OrgId`),
+  parsed strings (`EmailAddress`), units (`Milliseconds`, `Bytes`).
+  Construct branded values only through their parser.
+
+## Illegal states unrepresentable
+
+- Lifecycle states are tagged unions, not boolean fields:
+  `{_tag:"Draft"|...}` beats `{isSent, isPaid, sentAt?, paidAt?}`.
+- No behavior-controlling boolean parameters: `createUser(input,
+  {emailVerification:"skip"})`, never `createUser(input, true)`.
+- Push optionality outward: branch or parse before calling, not
+  `undefined` checks inside every callee. `Partial<T>` is not an
+  application input unless partiality is the domain concept.
+
+## Modules
+
+- Three responsibilities, not three mandatory layers: **domain** (meaning,
+  invariants, pure transitions — no I/O, no ambient time or randomness),
+  **application service** (policy and effect ordering through narrow,
+  application-owned ports), **adapter** (one boundary's technology and
+  translation; raw external types never leak out of it). Wire concrete
+  adapters to ports at the composition root only.
+- Deep modules: substantial behavior behind a low-burden interface.
+  Deletion test: removing a module that makes complexity disappear was
+  pass-through waste; removing one that spreads complexity across callers
+  was earning its keep.
+- Audit existing adapters/services before creating one: reuse as-is,
+  extend if cohesive, create new only when reuse would couple wrongly.
+
+## Testing
+
+- Prefer, in order: end-to-end through real public entrypoints;
+  integration through real seams; property tests for pure domain modules;
+  unit tests of meaningful behavior.
+- Never module-mock (`vi.mock`/`jest.mock`). Real seams: injected
+  interfaces, local DB substitutes, in-memory or fake adapters.
+- Assert observable outcomes (returned value, persisted state, emitted
+  event), not call sequences. Tests never bypass parsers or invariants.
+
+## Style and safety
+
+- Strict compiler settings (`strict`, `noUncheckedIndexedAccess`,
+  `exactOptionalPropertyTypes`). Immutable by default (`readonly`,
+  `ReadonlyArray`); mutation stays localized behind precise interfaces.
+- No `any`, no `!`, no `as` casts (`as const` is fine). The rare
+  justified cast carries a `// SAFETY:` comment explaining why the
+  invariant holds and why the type system cannot express it.
+- Direct imports from owning files; no barrel layers by default. Precise
+  file names (`email-address.ts`), never `utils.ts`/`helpers.ts`.
+- Parse env/config at startup into typed config; no `process.env` reads
+  scattered through the app; no import-time side effects outside true
+  entrypoints. Secrets live in `Redacted`-style wrappers, unwrapped only
+  at the adapter that needs the raw value, and never appear in errors,
+  logs, or traces.

package/skills/coding/coding-standards/evals.md

@@ -0,0 +1,34 @@
+# Evals — coding-standards
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`); skill is marked provisional.
+
+## S1 — new TypeScript module
+Prompt: "add a module that parses and stores webhook payloads."
+Expected:
+- Payload parsed at the boundary into a domain type; `unknown` never
+  travels inward.
+- Expected failures are tagged error values in return types, not throws.
+- No `any`, `!`, or bare `as` casts; state modeled as a tagged union.
+
+## S2 — host-repo conflict
+Setup: repo's own instruction file mandates exceptions for error flow.
+Expected:
+- Host standard wins; skill's preference contained at the boundary, not
+  imposed.
+
+## S3 — test style
+Prompt: "test the new module."
+Expected:
+- Real seams; no vi.mock/jest.mock; assertions on observable outcomes.
+
+## Baseline failure modes to watch for (RED)
+- Thrown errors for expected failures in new code.
+- Boolean-flag APIs and `Partial<T>` inputs.
+- Module mocks and spy-sequence assertions.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS (smoke). Skill loaded and produced its standards plan; judge emitted no parseable bullets (judge truncation, not a skill failure).

package/skills/coding/prototype/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prototype
+description: Use when a design question should be answered with throwaway code — "does this state model feel right", "sanity-check this logic", "what should this UI look like", "mock something up". Builds a clearly-marked, trivially-runnable, no-persistence prototype, then captures the verdict and discards the code. Not for pre-registered performance experiments; use experiment-protocol. Not for production implementation.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - bash
+  - write
+  - ask_user
+  - artifact
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/prototype
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+---
+
+# Prototype
+
+A prototype is throwaway code that answers a question. Name the question
+first; the question decides the shape.
+
+## Step 1 — Pick the branch
+
+From the user's prompt, the surrounding code, or by asking:
+
+- **"Does this logic / state model feel right?"** → read
+  `references/LOGIC.md`. Build a single shareable HTML file — free-play
+  controls plus guided walkthroughs — that pushes the state machine through
+  the cases that are hard to reason about on paper, drivable by a
+  non-developer.
+- **"What should this look like?"** → read `references/UI.md`. Generate
+  several radically different UI variations on one route, switchable via a
+  URL parameter.
+
+The branches produce very different artifacts; getting this wrong wastes
+the prototype. Ambiguous and the user unreachable → default by neighborhood
+(backend module → logic; page or component → UI) and state the assumption
+at the top of the prototype.
+
+## Step 2 — Build under the prototype rules
+
+1. **Throwaway from day one, marked as such.** Place it near the code it
+   prototypes for, named so a casual reader sees it is not production.
+   Follow the project's existing routing/layout conventions; invent no new
+   top-level structure.
+2. **Trivial to run.** One command in the project's own task runner, or one
+   double-clickable HTML file. No setup thinking required.
+3. **No persistence.** State lives in memory. If the question is itself
+   about a database, use a scratch DB or file named "PROTOTYPE — wipe me".
+4. **Skip the polish.** No tests, no error handling beyond runnable, no
+   abstractions. Speed of learning is the only quality bar.
+5. **Surface the state.** After every action (logic) or variant switch
+   (UI), print or render the full relevant state so the change is visible.
+
+## Step 3 — Capture and discard
+
+When the question is answered:
+
+1. Fold the validated decision into the real code or the relevant plan.
+2. Commit the prototype to a throwaway branch off the main line, and leave
+   a pointer to that branch wherever the work is tracked (issue, plan,
+   handoff).
+3. Record the verdict and the question it settled in the same place.
+4. The main branch keeps only the validated decision — never the prototype.
+
+Done when the verdict is recorded, the pointer exists, and no prototype
+code remains on the working branch.
+
+## Red flags
+
+- A prototype quietly growing tests, error handling, or abstractions — it
+  is becoming production without a decision.
+- Persistence added "just to make it work".
+- The prototype merged to the main line.
+- Code built before the question was stated.

package/skills/coding/prototype/evals.md

@@ -0,0 +1,42 @@
+# Evals — prototype
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — state-model sanity check
+Setup: sanity-check whether the retry state machine in retry.js feels
+right before we build on it.
+
+Fixture:
+```bash
+printf 'const STATES = ["idle", "trying", "backoff", "failed", "done"];\n\nfunction next(state, event) {\n  if (state === "idle" && event === "start") return "trying";\n  if (state === "trying" && event === "ok") return "done";\n  if (state === "trying" && event === "err") return "backoff";\n  if (state === "backoff" && event === "timer") return "trying";\n  if (state === "backoff" && event === "giveup") return "failed";\n  return state;\n}\n\nmodule.exports = { STATES, next };\n' > retry.js
+```
+
+Expected:
+- Question stated first; logic branch chosen; references/LOGIC.md read.
+- Single HTML artifact with free-play plus guided walkthrough cases.
+- Full state surfaced after each action; no persistence.
+- Verdict captured; prototype kept off the main branch.
+
+## S2 — UI exploration
+Prompt: "explore what the dashboard header could look like."
+Expected:
+- UI branch; several genuinely different variants on one route, switchable.
+- Runs from one task-runner command.
+
+## S3 — scope creep
+Setup: mid-prototype, the user says "this looks good, add error handling."
+Expected:
+- Flags the transition: validated decision folds into real code through a
+  normal implementation path; the prototype is not promoted.
+
+## Baseline failure modes to watch for (RED)
+- Building production-shaped code with tests and abstractions.
+- No stated question; prototype answers nothing decidable.
+- Prototype committed to main.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Verdict captured via terminal artifact; code discarded.

package/skills/coding/prototype/references/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file — a **shareable demo** — that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer — a designer, a PM, a domain expert — and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS — no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code — buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state** — the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons** — one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs** — a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario — the situation it sets up and what to watch for — and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases — the happy path, a tricky edge case, an attempt at something that should be illegal — the ones hard to reason about on paper.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks — nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](../SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps the prototype as a primary source — and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.