@ericrisco/rsc 1.1.5 → 1.1.6

package/skills/motion-craft/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: motion-craft
+description: "Use when an interface moves and the movement has to feel right — durations and easing, what must never animate, fixing motion that reads sluggish, cheap or janky, and reduced-motion. Web and native. NOT the visual system (that is `design`), NOT the graded critique (that is `design-loop`)."
+tags: [motion, animation, interface, craft, frontend]
+recommends: [design]
+profiles: [full]
+origin: risco
+---
+
+# Motion craft — movement that reads as intent
+
+Motion is not decoration laid over an interface. It is the interface **explaining what just
+happened**: what appeared, what it came from, what is still loading, what the user just did. When
+motion feels wrong the complaint is almost never "the curve is off" — it is "this feels cheap", or
+"slow", or "I don't know what happened". Those are the symptoms this skill exists to convert into
+decisions.
+
+## The one rule
+
+**Every animation answers a question the user is already asking.** If you cannot name the question,
+delete the animation — it is costing time and attention and returning nothing.
+
+| The user is asking | The motion that answers it |
+| --- | --- |
+| "Where did this come from?" | It enters from its origin, not from nowhere |
+| "Is it working?" | Immediate feedback, under 100ms, even before the result |
+| "What did I just do?" | The changed thing moves; nothing else does |
+| "Where did it go?" | It exits toward where it can be found again |
+| nothing | **no animation** |
+
+That table is the whole method. Everything below is how to honour it without shipping something
+that janks.
+
+## Duration: the only numbers worth memorising
+
+Movement is read as *slow* long before it is read as *long*. The usable range is narrower than most
+people expect, and the mistake is almost always **too slow**, not too fast.
+
+| What moves | Range | Why |
+| --- | --- | --- |
+| State on an element already on screen (hover, toggle, press) | 100–150ms | It must feel like a response, not an event |
+| Something entering or leaving in place (menu, tooltip, toast) | 150–250ms | Long enough to be seen, short enough not to be waited for |
+| A region rearranging (list reflow, panel) | 250–350ms | Bigger travel needs more time to stay legible |
+| A full view transition | 300–400ms | The ceiling. Past 400ms it is a wait, not a transition |
+
+Two rules that come from those numbers, not from taste:
+
+- **Exits are faster than entrances**, usually by about a third. The user has already decided; making
+  them watch the decision leave is the single most common way an interface feels sluggish.
+- **Distance and duration scale together, sub-linearly.** Doubling the travel does not double the
+  time. If a value grows past 400ms because the element crosses the screen, the layout is the
+  problem, not the timing.
+
+## Easing: three curves cover almost everything
+
+- **Entering, or responding to input** — start fast, settle slow (`ease-out` family). The user's
+  attention is already there; arriving quickly and settling reads as responsive.
+- **Leaving** — start slow, accelerate away (`ease-in` family). It matches how the eye lets go.
+- **Moving between two on-screen positions** — accelerate and decelerate (`ease-in-out` family).
+
+**Linear is for one thing only: continuous, non-positional change** — a progress bar filling, a
+spinner rotating, a colour crossfade. Linear on anything that moves in space reads as mechanical,
+because nothing physical starts at full speed.
+
+Springs are worth reaching for when the motion should feel *physical* — dragging, dismissing,
+anything the user's finger or pointer is still in contact with. They are the wrong tool for
+appearing and disappearing, where a bounce reads as indecision.
+
+## What must never animate
+
+This is where most jank comes from, and it is not a matter of degree.
+
+- **Never animate layout.** Width, height, top, left, margin, padding — each frame forces the engine
+  to recompute geometry. Animate transform and opacity, which do not.
+- **Never `transition: all`.** It is the shortest path to animating layout by accident. List the
+  properties.
+- **Never animate what the user is reading.** Text that moves while being read is illegible.
+- **Never block input on an animation.** The interface accepts the next action immediately, even
+  mid-motion. An animation that must finish before the user may act has become a modal dialog.
+- **Never animate more than one thing per event.** If three things move when one changed, the user
+  cannot tell which one mattered.
+
+## Reduced motion is not an edge case
+
+A real share of people have vestibular conditions for which large movement is nauseating, and they
+have told their operating system so. Honouring it is not optional and it is not a fallback to
+nothing:
+
+- **Keep** the feedback: opacity changes, colour, instant state.
+- **Remove** the travel: no sliding across the screen, no scaling, no parallax, no auto-playing loops.
+- The interface must still say what happened — it just says it without moving.
+
+An implementation with no reduced-motion branch is unfinished, the same way an interface with no
+error state is unfinished.
+
+## Diagnosing motion that feels wrong
+
+The complaint names the symptom; this maps it to a cause.
+
+| Complaint | Usually | Fix |
+| --- | --- | --- |
+| "Sluggish" | Duration too long, or the exit matches the entrance | Cut to the range above; make exits faster |
+| "Cheap" / "amateur" | Linear easing on positional movement, or bounce on entrances | Match curve to direction |
+| "Janky" / "stutters" | Animating layout properties | Move to transform and opacity |
+| "Distracting" | More than one thing moving per event | Animate only what changed |
+| "I don't know what happened" | Motion with no origin or destination | Move it from where it came from |
+| "Nice, but I'd turn it off" | No reduced-motion branch, or motion that repeats | Honour the setting; never loop what is not loading |
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Add motion because the screen feels static | Static is not a defect. Motion with no question to answer is noise with a frame cost. |
+| Copy a duration from a design you liked | You copied the number without its distance and its context. Take the range, verify against the feel. |
+| Animate a list so every item cascades in | Stagger past ~4 items becomes a queue the user waits through. Cap it, or drop it. |
+| Use a spring for a menu appearing | A bounce on an entrance reads as indecision. Springs are for what the pointer is still touching. |
+| Ship motion without checking reduced-motion | It is not an edge case. Unchecked means unfinished. |
+| Reach here for the visual system | Type, colour, spacing and composition are `../design/SKILL.md`. This skill only moves what that one placed. |
+
+## See Also
+
+- `../design/SKILL.md` — the visual system this motion serves.
+- `../design-loop/SKILL.md` — the graded critique that judges a finished screen, motion included.
+- `../design-dna/SKILL.md` — turning a look, motion rules included, into a reusable identity.
+- `../accessibility/SKILL.md` — the wider ground reduced-motion sits in.

package/skills/motion-craft/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: motion-craft
+
+should_trigger:
+  - prompt: "The menu animation feels sluggish, can you make it feel snappier?"
+    why: "The canonical case: a complaint about feel, which this skill converts into a duration and an easing decision."
+  - prompt: "What duration and easing should this dropdown use?"
+    why: "Directly the numbers this skill owns, for an element entering in place."
+  - prompt: "My list animation stutters when it reflows."
+    why: "Jank is the symptom of animating layout properties, which is the one hard rule here."
+  - prompt: "Añade una animación al abrir el panel, pero que no quede cutre."
+    why: "Same ask in Spanish; the trigger is the intent, not the language."
+  - prompt: "Does this respect prefers-reduced-motion? I don't think we handled it."
+    why: "Reduced-motion is treated here as part of finishing the work, not as an edge case."
+  - prompt: "Everything on the page moves at once when I click one button."
+    why: "More than one thing moving per event is a named diagnosis in this skill."
+
+should_not_trigger:
+  - prompt: "Design a landing page for my analytics SaaS — hero, pricing, the works."
+    route_to: "design"
+    why: "Type, colour, spacing and composition are the visual system, which this skill only moves once it exists."
+  - prompt: "Review this checkout screen and tell me how good it actually is, with a grade."
+    route_to: "design-loop"
+    why: "Graded critique of a finished screen is the loop's job; this skill builds motion, it does not judge screens."
+  - prompt: "This design came out great — turn it into a style I can reuse everywhere."
+    route_to: "design-dna"
+    why: "Codifying a look into a permanent identity is capture, not motion craft."
+  - prompt: "Make the site keyboard navigable and fix the contrast failures."
+    route_to: "accessibility"
+    why: "Accessibility beyond reduced-motion is its own ground; only the motion half lives here."
+  - prompt: "Our React app re-renders too much and the profiler shows wasted renders."
+    route_to: "react"
+    why: "A rendering performance problem is framework work, even when the symptom looks like stutter."
+
+capability:
+  - prompt: "This modal slides in over 600ms with a linear curve and it feels cheap. Fix it and say why."
+    why: "Exercises the two most common defects at once — too slow, and linear on positional movement — and demands the reasoning, not just new numbers."
+  - prompt: "We animate width and height on the sidebar and it janks on mobile. What do we do instead?"
+    why: "The layout-vs-compositor rule is the load-bearing piece of technical content here."

package/skills/motion-craft/scripts/verify.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# verify.sh — the never-animate list of `motion-craft`, made mechanical.
+#
+# The SKILL.md declares rules as binding ("never animate layout", "never
+# `transition: all`"). A rule declared binding without a mechanism that checks it
+# is a decorative gate: it buys the feeling of safety without the safety. So each
+# hard rule in the skill body has a row here, and each row has a fixture in
+# tests/motion-craft-rules.test.js that watches it FAIL and then PASS.
+#
+# Static and network-free. Everything WARNS by default; --strict makes findings
+# fatal, which is what CI should use.
+set -u
+TARGET="${1:-.}"
+STRICT=0
+[ "${2:-}" = "--strict" ] && STRICT=1
+[ "${1:-}" = "--strict" ] && { STRICT=1; TARGET="."; }
+
+warn_count=0
+warn() { printf '  ⚠  %s\n' "$1"; warn_count=$((warn_count + 1)); }
+ok()   { printf '  ✓  %s\n' "$1"; }
+
+# id <TAB> grep -E pattern <TAB> message
+# One row per hard rule in SKILL.md §"What must never animate". Adding a rule to
+# the prose without adding it here is what the test suite refuses to allow.
+#
+# Fields are TAB-separated on purpose: the patterns are extended regexes and are
+# full of `|`, so a pipe delimiter silently truncated every pattern at its first
+# alternation and only the one rule without alternation ever fired.
+rules() {
+  printf '%b\n' \
+    "transition-all\ttransition:[[:space:]]*all\t\`transition: all\` animates layout by accident — list the exact properties" \
+    "layout-anim\ttransition:[^;]*(width|height|top:|left:|right:|bottom:|margin|padding)\tanimating layout properties forces reflow every frame — use transform and opacity" \
+    "linear-move\t(transition|animation):[^;]*(transform|translate|scale)[^;]*linear\tlinear easing on positional movement reads as mechanical — nothing physical starts at full speed" \
+    "long-duration\t(transition|animation):[^;]*[^0-9]([5-9][0-9][0-9]|[0-9][0-9][0-9][0-9])ms\tover 400ms stops being a transition and becomes a wait"
+}
+
+files=$(find "$TARGET" \( -name node_modules -o -name .git -o -name dist -o -name build -o -name .next \) -prune -o \
+  \( -name '*.css' -o -name '*.scss' -o -name '*.tsx' -o -name '*.jsx' -o -name '*.ts' -o -name '*.js' -o -name '*.vue' -o -name '*.svelte' \) -print 2>/dev/null)
+
+echo "motion-craft — never-animate checks"
+if [ -z "$files" ]; then
+  echo "  (no style or component files found under $TARGET)"
+  exit 0
+fi
+
+while IFS=$'\t' read -r id pattern message; do
+  [ -z "$id" ] && continue
+  hits=$(printf '%s\n' "$files" | xargs grep -lEi -- "$pattern" 2>/dev/null | head -5)
+  if [ -n "$hits" ]; then
+    warn "$id: $message"
+    printf '        %s\n' $hits
+  else
+    ok "$id"
+  fi
+done <<< "$(rules)"
+
+# reduced-motion is a finishing condition, not an edge case: if anything animates
+# at all, the project must say what it does for people who asked for less motion.
+if printf '%s\n' "$files" | xargs grep -lEi -- '(transition|animation|@keyframes)' >/dev/null 2>&1; then
+  if printf '%s\n' "$files" | xargs grep -lEi -- 'prefers-reduced-motion' >/dev/null 2>&1; then
+    ok "reduced-motion: honoured somewhere"
+  else
+    warn "reduced-motion: this project animates and never mentions prefers-reduced-motion — unchecked means unfinished"
+  fi
+fi
+
+echo
+if [ "$warn_count" -gt 0 ]; then
+  echo "$warn_count finding(s)."
+  [ "$STRICT" -eq 1 ] && exit 1
+else
+  echo "No findings."
+fi
+exit 0

package/skills/react/SKILL.md

@@ -10,8 +10,8 @@ origin: risco
 
 **Hand-off — picking dependencies.** Which library to reach for (UI primitives, command menus,
 toasts, OTP inputs, charts, virtualization, drag and drop, state, styling, theming) is
-`../pick-ui-library/SKILL.md`'s — reach for it before hand-rolling a component. Animating what you
-install is `../animate/SKILL.md`'s.
+`../ui-engineering/SKILL.md`'s — build vs adopt is decided there, before hand-rolling a component. Animating what you
+install is `../motion-craft/SKILL.md`'s.
 
 
 > Build or review a fast, typed, correctly-architected **client-side** React single-page app bundled by Vite. No server runtime, no RSC tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is `../nextjs/SKILL.md`.

package/skills/react-native/SKILL.md

@@ -10,7 +10,7 @@ origin: risco
 
 **Hand-off — the app vs its motion.** Animation and gestures in a React Native app — Reanimated
 worklets on the UI runtime, gesture handoff, sheets, press feedback, haptics — are
-`../animate-expo/SKILL.md`'s, whose guidance applies to bare React Native as well as Expo.
+`../motion-craft/SKILL.md`'s, whose guidance is platform-agnostic and applies to bare React Native as well as Expo.
 
 
 You write the code that runs *inside* the app: render, navigate, animate, list, persist, and author native modules. Mobile is split across two skills by **verb** — run the verb test before doing anything:

package/skills/swift-ios/SKILL.md

@@ -12,8 +12,8 @@ origin: risco
 **Hand-off — the language vs the platform.** This skill owns the **platform**: SwiftUI/UIKit views,
 app lifecycle, Xcode, iOS APIs, App Store shipping. Language-level Swift — Swift 6 data-race safety
 and approachable concurrency, actors and task groups, `some` vs `any`, ARC and performance, Swift
-Testing, macros — is `../write-swift/SKILL.md`'s. A concurrency error, a hang, a data race or a
-retain cycle goes there, not here. Interface feel, springs and materials: `../apple-design/SKILL.md`.
+Testing, macros — is this skill's own ground. A concurrency error, a hang, a data race or a
+retain cycle belongs here. Interface feel, springs and materials: `../motion-craft/SKILL.md`.
 
 
 Native Apple-platform apps: the code is `.swift`, the UI is SwiftUI, and the compiler enforces actor isolation. If the answer is a `@MainActor`, `@Observable`, `async let`, `#expect`, `NavigationStack`, or `@Model`, you are in the right place.

package/skills/ui-engineering/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ui-engineering
+description: "Use when the question is how interface should be BUILT — component boundaries, state that belongs in the URL vs the component, loading/empty/error states, forms, optimistic updates, build vs adopt. NOT the visual system (`design`), NOT framework mechanics (`react`/`nextjs`)."
+tags: [interface, frontend, architecture, components, state, craft]
+recommends: [design, motion-craft]
+profiles: [core, full]
+origin: risco
+---
+
+# UI engineering — the decisions between the design and the framework
+
+There is a layer that neither the design skill nor the framework skill owns. The design says what
+the screen should be. The framework says how its API works. **In between sits every decision that
+makes an interface either durable or a maintenance tax** — and it is where most interface work
+actually goes wrong.
+
+Nothing here is framework-specific. These decisions are the same in React, Vue, Svelte, SwiftUI and
+plain HTML; only the syntax moves.
+
+## The one rule
+
+**State goes to the outermost place that still needs it, and no further.** Almost every interface
+tangle is that rule broken in one of two directions: state hoarded in a component that others need,
+or state hoisted into a global store that only one component ever reads.
+
+| Where the state lives | When that is right |
+| --- | --- |
+| **The URL** | Anything a user would bookmark, share, or expect the back button to restore: filters, tabs, pagination, the open item |
+| **The server** | Anything that outlives the session or belongs to more than one user |
+| **A shared parent** | Two siblings genuinely need it, and it dies with the screen |
+| **The component** | Nobody else reads it: hover, focus, an open menu, an in-flight draft |
+
+The most common and most expensive mistake is the first row: state that belongs in the URL kept in a
+component. It looks fine until someone reloads, shares a link, or presses back — and then the
+interface silently loses what the user did.
+
+## Every state, not just the happy one
+
+An interface is not finished when it renders data. It is finished when it renders **all five**:
+
+| State | The question it answers | The usual failure |
+| --- | --- | --- |
+| **Loading** | "Is it working?" | A spinner where the shape is already known — use the shape |
+| **Empty** | "Is it broken, or is there nothing?" | Blank. It must say which, and what to do next |
+| **Error** | "What now?" | A message with no action. Every denial carries its own way out |
+| **Partial** | "Some of it failed" | Ignored entirely; the screen shows a half-truth |
+| **Success** | "It worked" | Silence, so the user does it twice |
+
+The empty state is the one that gets skipped, and it is the first state a new user ever sees.
+
+## Component boundaries
+
+A component earns its existence by **hiding a decision**, not by being reused. Splitting for reuse
+alone produces the worst interfaces: a wrapper around a wrapper, each passing props through, none
+owning anything.
+
+Draw the boundary where:
+
+- it owns a piece of state nothing outside needs;
+- it can be described in one sentence without "and";
+- swapping its internals changes nothing outside it.
+
+Do **not** draw a boundary because a file is long. Long is not a defect; a file that does two
+unrelated things is, and it is usually short.
+
+## Forms
+
+Forms are where interfaces most often insult people, and the rules are unglamorous:
+
+- **Validate on blur, not on keystroke.** Telling someone their email is invalid while they are on
+  the third character is scolding them for not having finished.
+- **Never clear what they typed.** Not on error, not on refresh, not on navigation. Their input is
+  theirs.
+- **Disable the submit only while submitting**, never as a way of enforcing validity — a disabled
+  button with no reason is a dead end.
+- **The error goes next to the field**, and says what to do, not what is wrong.
+
+## Optimistic updates
+
+Show the result before the server confirms **only** when you can honestly undo it. That means: the
+operation is idempotent, the failure is rare, and reverting it is visible and comprehensible.
+
+Optimism on a destructive or an expensive action is a lie you will have to retract in front of the
+user. Deleting, paying, sending — those wait.
+
+## Build or adopt
+
+Adopting a component costs bundle size, an API you did not design, and an upgrade you will owe
+later. Building costs the accessibility work you will get wrong.
+
+The split is not about difficulty, it is about **who is the authority on the behaviour**:
+
+- **Adopt** for behaviour with a specification you would otherwise be reimplementing badly: focus
+  trapping, combobox semantics, date handling, virtualisation.
+- **Build** for anything that is your product's own logic wearing a UI, or where the library gives
+  you 60% and you fight the remaining 40% forever.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Put a filter or tab selection in component state | It belongs in the URL. Reload, share and back are part of the interface. |
+| Add a global store because passing props feels tedious | Tedious is not broken. Global state that one component reads is a leak with ceremony. |
+| Ship a screen with only the loaded state | Loading, empty, error and partial are not extras. The empty one is what a new user sees first. |
+| Split a component because the file got long | Length is not the defect. Two unrelated responsibilities are, and they are usually short. |
+| Show a delete as done before the server confirms | Optimism on a destructive action is a lie you will retract in public. |
+| Reach here for how the framework's hooks work | That is `../react/SKILL.md` or `../nextjs/SKILL.md`. This skill decides what to build; those decide how to express it. |
+
+## See Also
+
+- `../design/SKILL.md` — the visual system these decisions serve.
+- `../motion-craft/SKILL.md` — how the pieces here move once they exist.
+- `../design-loop/SKILL.md` — the graded critique that judges the result.
+- `../accessibility/SKILL.md` — the ground under focus, semantics and forms.

package/skills/ui-engineering/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: ui-engineering
+
+should_trigger:
+  - prompt: "Where should the filter state live — component, context or the URL?"
+    why: "The canonical case: the one rule this skill exists to apply."
+  - prompt: "How should I split these components? The file is getting big."
+    why: "Component boundaries, and the file-length premise is one this skill corrects."
+  - prompt: "We only render the loaded state. What else does this screen need?"
+    why: "The five states are the checklist this skill owns."
+  - prompt: "¿Valido el formulario mientras escribe o al salir del campo?"
+    why: "Form behaviour, in Spanish; the trigger is the decision, not the language."
+  - prompt: "Should I use a component library for the date picker or build it?"
+    why: "Build vs adopt, decided by who owns the behaviour's specification."
+  - prompt: "Can we show the delete as done immediately and roll back if it fails?"
+    why: "Optimistic updates, and this is the case where the answer is no."
+
+should_not_trigger:
+  - prompt: "Design the pricing page — layout, type scale, the colour system."
+    route_to: "design"
+    why: "The visual system is decided before this layer has anything to build."
+  - prompt: "My useEffect runs twice in development and I don't understand why."
+    route_to: "react"
+    why: "Framework mechanics. This skill decides what to build, not how the framework behaves."
+  - prompt: "The dropdown animation feels cheap, what duration should it use?"
+    route_to: "motion-craft"
+    why: "Once the component exists, how it moves is motion craft."
+  - prompt: "Grade this dashboard and tell me if it is actually good."
+    route_to: "design-loop"
+    why: "Judging a finished screen is the critique loop, not the build decisions."
+  - prompt: "Set up the Next.js App Router with server actions for this project."
+    route_to: "nextjs"
+    why: "Stack setup is the stack skill's; this one is framework-agnostic by construction."
+
+capability:
+  - prompt: "Our search page keeps its query and filters in component state. Users complain the back button loses everything. What is wrong and what is the fix?"
+    why: "The single most expensive instance of the one rule, stated as a real symptom rather than as theory."
+  - prompt: "This list screen shows a spinner, then rows. What states are we missing and why does each matter?"
+    why: "Forces the five-state checklist, including the empty state that a new user sees first."

package/skills/variant-explorer/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: variant-explorer
+description: "Use when someone wants OPTIONS rather than an answer — 'show me a few versions', picking between approaches by seeing them. Genuinely different candidates, cheap to throw away, trade-off named. NOT the critique that judges one (`design-loop`), NOT the spec (`specify`)."
+tags: [prototyping, divergence, options, exploration, decision]
+recommends: [design-loop]
+profiles: [full]
+origin: risco
+---
+
+# Variant explorer — several real options, cheap enough to discard
+
+"Show me a few versions and I'll pick" is a different request from "build this". It asks for
+**divergence**: several candidates that are actually different, each cheap enough that throwing it
+away costs nothing, with the difference between them stated out loud so a human can decide.
+
+Done badly it produces the thing that wastes the most time in creative work: three variations of one
+idea, dressed up as a choice.
+
+## The one rule
+
+**Variants must differ in a decision, not in a detail.** If two candidates could both be reached by
+editing the other, there is one candidate.
+
+```text
+Not variants:   the same layout in blue, in green, in dark
+Variants:       a single scrolling page · a three-step wizard · a table with inline editing
+```
+
+The test before showing anything: **name the decision each variant is taking.** If you cannot name
+it, or two share it, that set is not ready.
+
+## How many, and how finished
+
+- **Three.** Two reads as a false dichotomy; five past the point where a person can hold them side by
+  side. Three forces the middle option to justify itself.
+- **Finished enough to judge the decision, and no more.** If the decision is about structure, the
+  copy can be placeholder. If it is about tone, the layout can be crude. Polish that is not being
+  judged is polish you are asking someone to ignore.
+- **Comparable.** Same content, same constraints, same fidelity across all three. A variant that is
+  prettier wins for reasons nobody chose.
+
+## Making them genuinely different
+
+The failure mode is anchoring: the first idea contaminates the rest. Force divergence by generating
+each from a different starting constraint.
+
+| Angle | Ask |
+| --- | --- |
+| **Cheapest** | What if this had to ship this week? |
+| **Boldest** | What if we ignored what similar products do? |
+| **Fewest steps** | What if the user only did one thing? |
+| **Familiar** | What if it worked exactly like the thing they already know? |
+| **Inverted** | What if the primary and secondary swapped? |
+
+Pick three angles that are actually in tension for this problem. Do not run all five — the point is
+tension, not coverage.
+
+## Presenting them so a decision is possible
+
+Each candidate carries three things, and no more:
+
+1. **What decision it takes** — one sentence, in the user's terms.
+2. **What it costs** — the honest downside, not a hedge. A variant with no downside is one you have
+   not thought about.
+3. **What it would take to be wrong** — the fact that would kill it.
+
+Then: **a recommendation.** Presenting three options and standing back is not neutrality, it is
+handing the work back. Say which one you would pick and why, and make it easy to overrule.
+
+## When this is the wrong skill
+
+- The answer is already known and only needs building → build it. Manufacturing options to look
+  thorough wastes everyone's time.
+- The decision is reversible and cheap → just pick one and ship. Exploration is for decisions that
+  are expensive to unwind.
+- What is needed is a **judgement on one thing** → that is critique, not divergence.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Show the same idea in three colours | Those are not variants. Name the decision each takes; if you cannot, you have one. |
+| Polish one candidate more than the others | It will win on polish, not on the decision. Same fidelity, always. |
+| Present five or six to be thorough | Past three, they stop being compared and start being skimmed. |
+| Give options with no recommendation | Standing back is not neutrality; it hands the work back to the person who asked. |
+| Explore a decision that is cheap to reverse | Just ship one. Divergence is for what is expensive to unwind. |
+| Keep iterating on the winner here | Once one is chosen, refining it is `../design-loop/SKILL.md` or the relevant build skill. |
+
+## See Also
+
+- `../design-loop/SKILL.md` — the graded critique that takes over once a direction is chosen.
+- `../specify/SKILL.md` — when what is missing is an agreed WHAT/WHY, not options.
+- `../design/SKILL.md` — building the chosen direction properly.

package/skills/variant-explorer/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: variant-explorer
+
+should_trigger:
+  - prompt: "Show me a few versions of this onboarding and I'll pick one."
+    why: "The canonical phrasing: options to choose from, not an answer."
+  - prompt: "Give me three directions for how this could work before we commit."
+    why: "Explicit divergence ahead of an expensive decision."
+  - prompt: "Enséñame varias opciones de cómo montar el checkout, que ya elijo yo."
+    why: "Same request in Spanish; the trigger is the ask for options."
+  - prompt: "I can't decide between a wizard and a single page. Can I see both?"
+    why: "Two named approaches where seeing them is what settles it."
+  - prompt: "What are some different ways we could structure this dashboard?"
+    why: "Open-ended exploration of structural decisions, which is exactly divergence."
+  - prompt: "Before we build it, I want to compare a couple of approaches side by side."
+    why: "Comparability is the property this skill guarantees."
+
+should_not_trigger:
+  - prompt: "Review this checkout screen and grade it."
+    route_to: "design-loop"
+    why: "Judging one finished thing is critique, the opposite of divergence."
+  - prompt: "We need to agree what this feature is for before anyone builds it."
+    route_to: "specify"
+    why: "A missing WHAT/WHY is a spec problem; options would be premature."
+  - prompt: "Build the pricing page we agreed on last week."
+    route_to: "design"
+    why: "The decision is already made; manufacturing options would waste the time this skill is meant to save."
+  - prompt: "Which colour should the primary button be?"
+    route_to: "design"
+    why: "Cheap and reversible, and a detail rather than a decision — the explicit non-case here."
+  - prompt: "Run an A/B test to see which headline converts better."
+    route_to: "ab-testing"
+    why: "Measuring a winner with users is experimentation, not showing a human candidates to choose from."
+
+capability:
+  - prompt: "Give me three options for this signup flow. Make sure they are actually different, not the same thing restyled."
+    why: "Goes straight at the failure mode this skill exists to prevent, and demands the decision behind each be nameable."
+  - prompt: "Here are three variants I made. Are these real alternatives or the same idea three times?"
+    why: "Applies the one rule as a test on someone else's set, which is where it is hardest and most useful."