@ericrisco/rsc 1.0.26 → 1.0.28

package/skills/review-animations/evals/cases.yaml

@@ -0,0 +1,34 @@
+skill: review-animations
+
+should_trigger:
+  - prompt: "Review the animations in this pull request and tell me what's wrong with them."
+    why: "Reviewing motion in a diff: the skill's core object."
+  - prompt: "Is the easing and duration on this modal transition right?"
+    why: "A judgement call against the easing and duration standards."
+  - prompt: "Check this component's motion against a strict craft bar before I merge it."
+    why: "The bar and the merge gate are what this skill provides."
+  - prompt: "Critique the transitions I just wrote — be harsh."
+    why: "Default-to-flagging posture; approval is earned."
+  - prompt: "Did I get the transform-origin and the reduced-motion handling right on this popover?"
+    why: "Two of the ten non-negotiable standards, named directly."
+
+should_not_trigger:
+  - prompt: "Audit the animations across the whole app and give me a prioritized roadmap of fixes."
+    route_to: "improve-animations"
+    why: "Whole-codebase audit producing plans, not a verdict on one diff."
+  - prompt: "Animate this dropdown for me with the right curve and duration."
+    route_to: "animate"
+    why: "Building the animation, not reviewing one."
+  - prompt: "Review this pull request for SQL injection and missing authorization checks."
+    route_to: "code-review"
+    why: "Non-motion code review; this skill declines and points there."
+  - prompt: "What could be animated in this settings page that isn't animated today?"
+    route_to: "find-animation-opportunities"
+    why: "Looking for absent motion, not judging present motion."
+  - prompt: "Pick a library for the command palette instead of the div-based one we have."
+    route_to: "pick-ui-library"
+    why: "A dependency choice, not a motion review."
+
+capability:
+  - scenario: "A diff adds `transition: all 400ms ease-in` and a `transform: scale(0)` entrance to a popover with `transform-origin: center`, and no reduced-motion handling anywhere in the project."
+    expect: "Runs scripts/verify.sh first so the countable findings come from the checker (transition-all, ease-in-ui, scale-zero-entrance, origin-center-popover, reduced-motion-missing) and spends judgement on frequency, purpose and cohesion. Blocks rather than approves, and every finding carries the exact replacement value."

package/skills/review-animations/references/standards.md

@@ -0,0 +1,187 @@
+# Animation Standards Reference
+
+The precise values, curves, and rules behind the review. Cite these in findings instead of approximating. Distilled from Emil Kowalski's design engineering philosophy.
+
+## Should it animate? (frequency table)
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever. |
+| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare / first-time (onboarding, feedback, celebrations) | Can add delight |
+
+**Never animate keyboard-initiated actions** — they repeat hundreds of times daily; animation makes them feel slow and disconnected. (Raycast has no open/close animation — correct for something used hundreds of times a day.)
+
+Valid purposes for motion: spatial consistency, state indication, explanation, feedback, preventing jarring change. "It looks cool" on a frequently-seen element is not valid.
+
+## Easing
+
+Decision order:
+- Entering or exiting → **`ease-out`** (starts fast, feels responsive)
+- Moving / morphing on screen → **`ease-in-out`**
+- Hover / color change → **`ease`**
+- Constant motion (marquee, progress) → **`linear`**
+- Default → **`ease-out`**
+
+**Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.
+
+Built-in CSS easings are too weak. Use strong custom curves:
+
+```css
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
+```
+
+Find curves at [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) — don't hand-roll from scratch.
+
+## Duration
+
+| Element | Duration |
+| --- | --- |
+| Button press feedback | 100–160ms |
+| Tooltips, small popovers | 125–200ms |
+| Dropdowns, selects | 150–250ms |
+| Modals, drawers | 200–500ms |
+| Marketing / explanatory | Can be longer |
+
+**Rule: UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. Faster spinners make load feel faster (same actual time). Instant tooltips after the first (skip delay + animation) make a toolbar feel faster.
+
+## Physicality
+
+- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
+- **Origin-aware popovers.** Scale from the trigger, not center:
+  ```css
+  .popover { transform-origin: var(--transform-origin); } /* Base UI */
+  ```
+  **Modals are exempt** — they appear centered in the viewport, keep `transform-origin: center`.
+- **Button press feedback.** `transform: scale(0.97)` on `:active`, `transition: transform 160ms ease-out`. Subtle (0.95–0.98). Applies to any pressable element.
+
+## Springs
+
+Feel natural because they simulate physics; no fixed duration — they settle on parameters. Use for: drag with momentum, "alive" elements (Dynamic Island), interruptible gestures, decorative mouse-tracking.
+
+```js
+// Apple-style (easier to reason about) — recommended
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+
+// Traditional physics (more control)
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+Keep bounce subtle (0.1–0.3); avoid bounce in most UI — reserve for drag-to-dismiss and playful interactions. Springs maintain velocity when interrupted (keyframes restart from zero), so they're ideal for gestures users may reverse mid-motion.
+
+Mouse interactions: interpolate with `useSpring` rather than tying value directly to mouse position (direct = artificial, no momentum). Only do this when the motion is decorative.
+
+## Interruptibility
+
+CSS **transitions** can be interrupted and retargeted mid-animation; **keyframes** restart from zero. For anything triggered rapidly (toasts being added, toggles), transitions are smoother.
+
+```css
+/* Interruptible — good for dynamic UI */
+.toast { transition: transform 400ms ease; }
+
+/* Not interruptible — avoid for dynamic UI */
+@keyframes slideIn { from { transform: translateY(100%); } to { transform: translateY(0); } }
+```
+
+Use `@starting-style` for entry without JS:
+
+```css
+.toast {
+  opacity: 1; transform: translateY(0);
+  transition: opacity 400ms ease, transform 400ms ease;
+  @starting-style { opacity: 0; transform: translateY(100%); }
+}
+```
+
+Legacy fallback: `useEffect(() => setMounted(true), [])` + `data-mounted` attribute.
+
+## Asymmetric timing
+
+Slow where the user is deciding, fast where the system responds.
+
+```css
+.overlay { transition: clip-path 200ms ease-out; }            /* release: fast */
+.button:active .overlay { transition: clip-path 2s linear; }  /* press: slow, deliberate */
+```
+
+## Performance
+
+- **Only animate `transform` and `opacity`** — they skip layout/paint and run on the GPU. `padding`/`margin`/`height`/`width`/`top`/`left` trigger all three rendering steps.
+- **Don't drive child transforms via a CSS variable on the parent** — it recalcs styles for all children. Set `transform` directly on the element.
+  ```js
+  element.style.setProperty('--swipe-amount', `${d}px`); // bad: recalc on all children
+  element.style.transform = `translateY(${d}px)`;        // good: only this element
+  ```
+- **Framer Motion shorthands are NOT hardware-accelerated.** `x`/`y`/`scale` run on the main thread via rAF and drop frames under load. Use the full transform string:
+  ```jsx
+  <motion.div animate={{ x: 100 }} />                          // drops frames under load
+  <motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
+  ```
+- **CSS animations beat JS under load** — they run off the main thread; rAF-based animations stutter while the browser loads/scripts/paints. Use CSS for predetermined motion, JS for dynamic/interruptible.
+- **WAAPI** gives JS control with CSS performance (hardware-accelerated, interruptible, no library):
+  ```js
+  element.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
+    { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' });
+  ```
+
+## Transforms & clip-path
+
+- **`translate` percentages** are relative to the element's own size — `translateY(100%)` moves by the element's height regardless of dimensions (how Sonner/Vaul position toasts/drawers). Prefer over hardcoded px.
+- **`scale()` scales children too** (font, icons, content) — a feature for press feedback.
+- **3D**: `rotateX/Y` + `transform-style: preserve-3d` for depth/orbit/flip without JS.
+- **`clip-path: inset(t r b l)`** is a powerful animation tool: each value eats in from that side. Uses: reveal-on-scroll (`inset(0 0 100% 0)` → `inset(0 0 0 0)`), hold-to-delete overlay, seamless tab color transitions (duplicate + clip the active copy), comparison sliders.
+
+## Gestures & drag
+
+- **Momentum dismissal**: don't require crossing a distance threshold — compute velocity (`Math.abs(distance)/elapsedMs`); dismiss if `> ~0.11`. A flick should be enough.
+- **Damping at boundaries**: dragging past a natural edge moves less the further you go (real things slow before stopping).
+- **Pointer capture** once dragging starts, so it continues when the pointer leaves bounds.
+- **Multi-touch protection**: ignore extra touch points after the drag begins (`if (isDragging) return`) — prevents jumps.
+- **Friction over hard stops** — allow over-drag with rising resistance rather than an invisible wall.
+
+## Masking imperfect crossfades
+
+When a crossfade shows two overlapping states despite tuning easing/duration, add subtle `filter: blur(2px)` during the transition to blend them into one perceived transformation. Keep blur < 20px (heavy blur is expensive, especially Safari).
+
+## Stagger
+
+Stagger group entrances; 30–80ms between items. Longer delays feel slow. Stagger is decorative — never block interaction while it plays.
+
+```css
+.item { opacity: 0; transform: translateY(8px); animation: fadeIn 300ms ease-out forwards; }
+.item:nth-child(2) { animation-delay: 50ms; }
+.item:nth-child(3) { animation-delay: 100ms; }
+@keyframes fadeIn { to { opacity: 1; transform: translateY(0); } }
+```
+
+## Accessibility
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
+}
+@media (hover: hover) and (pointer: fine) {
+  .element:hover { transform: scale(1.05); } /* gate hover motion — touch fires false hovers on tap */
+}
+```
+
+```jsx
+const reduce = useReducedMotion();
+const closedX = reduce ? 0 : '-100%';
+```
+
+Reduced motion means fewer and gentler animations, not zero — keep transitions that aid comprehension, remove movement/position changes.
+
+## Debugging (recommend in reviews when feel is uncertain)
+
+- **Slow motion**: bump duration 2–5× or use DevTools animation inspector. Check colors crossfade cleanly, easing doesn't stop abruptly, `transform-origin` is right, coordinated properties stay in sync.
+- **Frame-by-frame**: Chrome DevTools Animations panel reveals timing drift between coordinated properties.
+- **Real devices** for gestures (drawers, swipe) — connect a phone, hit the dev server by IP, use Safari remote devtools.
+- **Fresh eyes next day** — imperfections invisible during development surface later.
+
+## Cohesion
+
+Match motion to the component's personality: playful can be bouncier; a professional dashboard should be crisp and fast. Sonner feels right partly because easing, duration, design, and even the name are in harmony — slightly slower, `ease` rather than `ease-out`, to feel elegant. Opacity + height in entering/exiting lists is trial and error; there's no formula — adjust until it feels right.

package/skills/review-animations/scripts/verify.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+#
+# verify.sh — the checkable half of the motion craft bar.
+#
+# WHAT THIS IS
+#   The source material for these skills (emilkowalski/skills, MIT) ships its "Never Ship" bar as
+#   a markdown table: prose an agent may or may not honor. Part of that bar is a plain pattern in
+#   the code — `transition: all`, an entrance from `scale(0)`, `ease-in` on a UI transition — and
+#   anything that is a pattern belongs in a binary, not in a paragraph (constitution P1).
+#
+#   So this script owns the countable half, and the SKILL.md bodies own the half that needs
+#   judgement (is the frequency tier right? does the motion have a purpose? does it feel right?).
+#   Nothing here can tell you whether an animation feels good. It tells you when it is definitely
+#   wrong.
+#
+# WHAT IT CHECKS
+#   - the tell registry: one row per checkable motion defect, iterated generically — see
+#     motion_tell_table(). Every row has a fixture in tests/fixtures/motion-tells/ and is driven
+#     from tests/motion-tells.test.js; a row without a fixture fails the suite.
+#   - one counter that cannot be a row: motion present with no prefers-reduced-motion guard
+#     anywhere. Absence of a guard is not a pattern match, so it gets its own check and its own
+#     named test.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   bash verify.sh              # fail-severity rows break the build; warns are advisory
+#   bash verify.sh --strict     # treat warnings as failures too
+#
+# EXIT CODES
+#   0  no fail-severity finding (and no warning, under --strict)
+#   1  a fail-severity finding, or --strict with any warning
+#   2  bad usage
+#
+# Missing tools are SKIPPED with a notice, never failed.
+
+set -euo pipefail
+
+# --- portability: runs on stock macOS bash 3.2 ------------------------------
+# No mapfile, no associative arrays, no `${arr[@]}` under set -u — same constraint as design's
+# verify.sh, for the same reason: the default /bin/bash on macOS is 3.2.
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+STRICT=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --strict) STRICT=1; shift ;;
+    -h|--help) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) printf 'unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+SELF_NAME="$(basename "$0")"
+
+ok()   { printf '%s  ok %s  %s\n'   "$GREEN" "$NC" "$1"; ok_count=$((ok_count + 1)); }
+skip() { printf '%sskip %s  %s\n'   "$YELLOW" "$NC" "$1"; skip_count=$((skip_count + 1)); }
+warn() { printf '%swarn %s  %s\n'   "$YELLOW" "$NC" "$1"; warn_count=$((warn_count + 1)); }
+fail() { printf '%sfail %s  %s\n'   "$RED" "$NC" "$1"; fail_count=$((fail_count + 1)); }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+search() {
+  [ "$#" -gt 0 ] || return 1
+  # VERIFY_FORCE_GREP=1 pins the grep branch so the suite can prove both engines agree, instead
+  # of only exercising whichever one happens to be installed.
+  if have rg && [ -z "${VERIFY_FORCE_GREP:-}" ]; then
+    rg -n --no-heading --glob "!$SELF_NAME" "$@"
+  else
+    local pattern="${*: -1}"
+    grep -rnE \
+      --exclude="$SELF_NAME" \
+      --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next \
+      --exclude-dir=dist --exclude-dir=build \
+      "$pattern" . 2>/dev/null
+  fi
+}
+
+# --- the tell registry ------------------------------------------------------
+# Columns, delimited by %% (the pattern column needs `|` for ERE alternation):
+#   id %% sev %% extensions %% POSIX-ERE pattern %% what to do instead / the legit exception
+#
+# Patterns are POSIX ERE: no lookahead, no \b, no \s — they must behave identically under rg and
+# under grep -E. The bar they encode is adapted from emilkowalski/skills (MIT).
+#
+# Severity is load-bearing, not decoration. `fail` is for a defect with no legitimate reading;
+# `warn` is for a pattern whose exception is real and cannot be seen from one line (a centered
+# modal, an accordion animating height). A table where everything fails gets switched off (P7).
+motion_tell_table() {
+  cat <<'TELLS'
+transition-all%%fail%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%transition:[[:space:]]*all|transition-all%%transition: all animates every property that ever changes, including layout ones, and janks. Name the exact properties instead: transition-property: transform, opacity
+scale-zero-entrance%%fail%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%scale\(0\)|scale3d\(0,|scale:[[:space:]]*0[,;}[:space:]]%%nothing in the real world appears from nothing, so an entrance from zero scale reads as broken. Start from scale(0.9)-scale(0.97) plus opacity: 0
+ease-in-ui%%fail%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%(^|[^a-zA-Z])ease-in([^-]|$)%%ease-in starts slow, delaying the exact moment the user is watching, so the interface feels sluggish. Use ease-out, or the stronger cubic-bezier(0.23, 1, 0.32, 1). Legitimate exception: an exit that must accelerate off-screen
+origin-center-popover%%warn%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%transform-origin:[[:space:]]*center%%a popover, dropdown, menu or tooltip should grow out of the trigger that opened it, not out of its own middle. Use transform-origin: var(--transform-origin). Legitimate exception: a modal, which is not anchored to a trigger and stays centered
+layout-property-animation%%warn%%css,scss%%transition-property:[[:space:]]*(width|height|margin|padding|top|left)|transition:[[:space:]]*(width|height|margin|padding|top|left)[[:space:]]%%animating a layout property triggers layout, paint and composite every frame. Animate transform and opacity instead. Legitimate exception: an accordion height, which has no transform equivalent
+motion-shorthand-under-load%%warn%%tsx,jsx,ts,js%%animate=\{\{[[:space:]]*(x|y|scale):%%the Motion x/y/scale shorthands are not hardware-accelerated: they run on the main thread and drop frames while the page is busy. Use the full transform string: animate={{ transform: "translateX(100px)" }}
+TELLS
+}
+
+run_motion_tell_table() {
+  local line id sev globs pat msg hits exts rest
+  # NOT `IFS='%%'`: IFS is a set of characters, so it would split on a single `%`. Parameter
+  # expansion splits on the two-character delimiter exactly, which the pattern column needs to
+  # keep its ERE `|`.
+  while IFS= read -r line; do
+    case "$line" in ''|'#'*) continue ;; esac
+    id="${line%%"%%"*}";    rest="${line#*"%%"}"
+    sev="${rest%%"%%"*}";   rest="${rest#*"%%"}"
+    globs="${rest%%"%%"*}"; rest="${rest#*"%%"}"
+    pat="${rest%%"%%"*}";   msg="${rest#*"%%"}"
+    exts="${globs//,/|}"
+    # Two post-filters, both taken from design/scripts/verify.sh where they were learned from a
+    # real run: keep only the extensions the row declares (anchored before the first colon, so it
+    # behaves the same under rg and grep and never matches content that merely names a file), and
+    # drop matches that sit inside a code comment. `ease-in` in `/* not ease-in */` is not code,
+    # and flagging it trains the reader to ignore the tool.
+    hits="$(search "$pat" 2>/dev/null \
+      | grep -E "^[^:]*\.($exts):" \
+      | grep -vE "^[^:]*:[0-9]+:[[:space:]]*(//|/\*|\*[^a-zA-Z]|#|<!--|\{/\*)" || true)"
+    if [ -n "$hits" ]; then
+      case "$sev" in
+        warn) warn "$id: $msg" ;;
+        *)    fail "$id: $msg" ;;
+      esac
+      printf '%s\n' "$hits" | head -n 5
+    fi
+  done <<EOF
+$(motion_tell_table)
+EOF
+}
+
+# --- the counter that cannot be a row ---------------------------------------
+# Absence of a guard has no line to match, so it cannot ride the generic mechanism. It carries its
+# own named test instead of pretending to be a row.
+reduced_motion_counter() {
+  # Only meaningful where motion actually exists: telling a backend repo to add a reduced-motion
+  # guard is the noise that gets a checker switched off.
+  if search 'transition:|transition-property|@keyframes|animation:|animate=\{|useSpring|animate-\[' >/dev/null 2>&1; then
+    if search 'prefers-reduced-motion|useReducedMotion|motion-safe:|motion-reduce:' >/dev/null 2>&1; then
+      ok "reduced-motion-missing: motion is present and a reduced-motion guard was found"
+    else
+      fail "reduced-motion-missing: this project animates but no prefers-reduced-motion guard was found anywhere. Reduced motion means fewer and gentler animations, not zero: keep opacity and color transitions that aid comprehension, drop movement and position changes"
+    fi
+  else
+    skip "reduced-motion-missing: no motion found in this project, nothing to guard"
+  fi
+}
+
+# --- run --------------------------------------------------------------------
+run_motion_tell_table
+reduced_motion_counter
+
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/specify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specify
-description: "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of SDD. Turns a one-line intent into problem, goals, users, scope, behaviour and acceptance criteria, via one-question-at-a-time dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`)."
+description: "Use when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of SDD. Turns a one-line intent into problem, goals, users, scope, behaviour and acceptance criteria, via frontier-round dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`)."
 tags: [sdd, spec, requirements]
 recommends: [clarify, plan]
 profiles: [core, full]
@@ -29,9 +29,11 @@ A **yes engages autopilot** (`../sdd/SKILL.md`): you still write the spec and ev
 
 ## The one rule that defines this skill
 
-**No implementation leaks.** The moment the spec names a framework, a table schema, a library, an endpoint shape, a file path, or an algorithm, it has stopped being a spec. Those decisions belong to `plan` and the stack skills. Specify describes the *observable behaviour and the reason for it*; the system that delivers it is deliberately left open.
+A spec is a **contract**: what the system will observably do, and why that matters. Every line either belongs in the contract or belongs to how the contract gets honoured — and the second kind is `plan`'s, not yours. Framework, table schema, library, endpoint shape, file path, algorithm: all of them are how, so the moment one appears the document has stopped being a contract.
 
-If you cannot describe a requirement without naming the technology, you have found a real question — record it as a point to clarify, do not guess the answer.
+One question settles every judgement call in this skill: **is this a clause of the contract, or a detail of how it gets met?**
+
+If you cannot state a requirement without naming the technology, that is a real open question — record it as a typed point to clarify, do not guess the answer.
 
 ## Model tier — `balanced` (opt-in routing)
 
@@ -41,23 +43,25 @@ This phase's default model tier is **`balanced`** — it drafts the what/why spe
 
 Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical level and accompaniment level, and adapt:
 
-- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the spec's scope. Draft, show, move on.
+- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the contract. Draft, show, move on.
 - **L1 "breve"** — one line of *why* per question; ask the few that genuinely matter.
 - **L2 "explica decisiones"** — justify each requirement as you record it; surface the trade-offs you inferred.
-- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one question at a time), confirm each answer before recording it. Ideal for non-technical users.
+- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one round per frontier, never crossing a dependency), confirm each answer before recording it. Ideal for non-technical users.
 
 If no profile exists, default to non-technical framing and keep questions plain. Never assume fluency.
 
-## Questioning discipline — one at a time, only where you can't infer
+## Questioning discipline — ask the frontier, never cross a dependency
 
-The failure mode of specs is the wall of twenty questions. Avoid it:
+The failure mode of specs is the wall of twenty questions. The cure is not one question per turn: that spends a turn of the user's time per question even when the questions do not touch each other. The cure is the **frontier**.
 
 1. **Infer first.** Read the `constitution` (`02-DOCS/wiki/sdd/constitution.md`), the existing wiki, and sibling specs. Fill every section you reasonably can from what already exists.
-2. **Ask only the gaps that change the spec.** A question earns its place only if a different answer would change scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become *points to clarify*, not questions.
-3. **One focused question per turn.** Ask, wait, record, then ask the next. Never batch. Phrase in the user's technical register.
-4. **When inference and asking both fail, mark it.** Anything you cannot resolve in this pass becomes an explicit entry in *Points to clarify* — that list is the handoff contract to the `clarify` phase, not a defect.
+2. **Ask only the gaps that change the contract.** A gap earns a question only if a different answer would move scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become typed *points to clarify*, not questions.
+3. **Ask the whole frontier in one round.** The frontier is every remaining gap whose prerequisites are already settled — the questions you can ask *now* without guessing at answers you have not heard yet. Number them, give each your recommended answer, then wait. Where the harness offers a native question selector, use it; where it does not, emit the same round as numbered text.
+4. **Never cross a dependency.** A gap whose answer depends on another question open in *this* round belongs to a later round. Recompute the frontier after every set of answers: settled decisions push it outward and unblock what waited on them. If an answer redefines a question you already emitted in the same round, discard that question out loud and re-ask it next round rather than using an answer given under a premise that just moved.
+5. **Facts are your job; decisions are the user's.** When a frontier question needs a fact from the environment, go find it — and do not block on it. A running search is an unsettled prerequisite, so only the questions downstream of it wait; ask the rest of the frontier now.
+6. **When inference and asking both fail, type it.** Anything unresolved becomes a typed entry in *Points to clarify* — the handoff contract to `clarify`, not a defect.
 
-Stop asking when the WHAT and WHY are complete enough to plan against. Remaining unknowns live in *Points to clarify*; you do not need every answer before writing the file.
+A frontier of one is one question, and needs no apology. A frontier of zero is no question at all: never invent one to look diligent.
 
 ## What a good spec contains
 
@@ -71,7 +75,7 @@ Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/s
 | Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
 | Behaviour | What the system does, in observable terms, incl. main + edge + error paths | A verb that's actually a HOW ("queries", "caches") |
 | Acceptance criteria | Testable, binary checks that say "done" | Vague critera ("works well", "is fast") |
-| Points to clarify | Open questions, assumptions made, decisions deferred | Pretending there are none |
+| Points to clarify | The typed handoff to `clarify` — see the four types below | An untyped list, or pretending there are none |
 
 ### Acceptance criteria carry the weight
 
@@ -85,6 +89,33 @@ Then they see an empty-cart message and the "pay" button is disabled
 
 A criterion that needs a human to "decide if it's good enough" is not done yet — sharpen it or move the soft part to *Points to clarify*.
 
+### Points to clarify carry a type
+
+*Points to clarify* is the handoff to `clarify`, and it holds four different objects that need four
+different actions. An untyped list makes `clarify` treat all of them as questions, so it re-asks what
+you already decided and touches what you deliberately deferred. Type every entry:
+
+| Type | What it is | What `clarify` does with it |
+| --- | --- | --- |
+| **pregunta abierta** | Formulable with precision right now, unanswered | Asks it |
+| **suposición tomada** | You decided it; the basis is written down | Validates it — does it still hold? |
+| **decisión diferida** | Sharp, out of this cycle on purpose | Leaves it alone |
+| **área no formulable** | Known to be coming, not yet sharp enough to phrase | Notes it; it graduates when it sharpens |
+
+The test that separates the last two from a question is **sharpness, not difficulty**: *can you state
+the question precisely now?* — not *can you answer it?* Sharp → **pregunta abierta**. Not sharp →
+**área no formulable**. Beyond what this change is for → `Non-goals`, where it never graduates.
+
+Write the type in bold at the head of the entry, and give a `suposición tomada` its basis:
+
+```text
+- **suposición tomada** — el enlace caduca en minutos, no en horas. *Base:* el patrón de los
+  proveedores que ya usamos. *Riesgo:* si el soporte pide horas, el criterio de aceptación cambia.
+```
+
+An entry with no type is read as **pregunta abierta**, the costliest of the four. The default never
+saves you work.
+
 ## The pass, end to end
 
 Run these in order. It is a collaborative dialogue, not a form you fill in silence — and **you do not skip to a design dump.** Track the steps with a todo list so none is dropped.
@@ -94,23 +125,40 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 2. SCOPE check            → if the request is several independent subsystems, DECOMPOSE into sub-specs first,
                             then brainstorm the FIRST one; each gets its own spec → plan → build cycle
 3. RESTATE in one sentence→ confirm you understood the intent before anything else
-4. ASK, one at a time     → only the gaps that change scope; multiple-choice when you can; wait, record, repeat
+4. ASK the frontier       → only gaps that change the contract; whole frontier per round, numbered, each
+                            with your recommendation; never cross a dependency; wait, record, recompute
 5. PROPOSE 2-3 approaches → distinct directions with honest trade-offs; lead with your recommendation and why
 6. PRESENT the design     → section by section (problem, users, behaviour, acceptance), scaled to complexity;
                             after EACH section ask "does this look right?" and adjust before moving on
 7. WRITE the spec         → 02-DOCS/wiki/sdd/specs/<slug>.md (WHAT/WHY), index it in 02-DOCS/wiki/index.md
                             (the Knowledge map; root CLAUDE.md keeps only a short pointer), commit if a repo
-8. SELF-REVIEW            → scan for TODO/placeholder, contradictions, ambiguity, scope creep; fix inline.
-                            On L2/L3 or a high-risk spec, also dispatch a FRESH-EYES review (below)
+8. SELF-REVIEW            → run the EXIT GATE (below) until green; scan for contradictions, ambiguity,
+                            scope creep; fix inline. On L2/L3 or high risk, add a FRESH-EYES review
 9. USER APPROVES          → ask them to read the written spec and confirm; loop on changes until they approve
 10. HAND OFF              → only now, result envelope → clarify/plan. NEVER to implement.
 ```
 
-**The gate is steps 5-9, and it is the point of this skill.** Implementation does not begin — not `plan`-to-code, not a stack skill, not "just a quick version" — until the user has approved the design at step 9. This holds for **every** feature, including ones that feel too small to design; "too simple to spec" is exactly where unexamined assumptions cost the most. The only thing that skips the loop is a literal one-line, zero-risk change (a typo, a copy tweak) — name it as such and do it.
-```
+**Steps 5-9 are the gate**, stated once under *Detect the moment* above and not restated here: approval at step 9 is what unlocks implementation.
 
 `<slug>` is a short kebab-case name derived from the feature (e.g. `bulk-csv-import`, `magic-link-login`). If a spec with that slug exists, read it and update rather than overwrite.
 
+### Exit gate — checked, not felt
+
+"Complete enough to plan against" cannot tell done from not-done, and the write/review/approve steps
+are visible while you are still asking, pulling attention toward being finished. So the bound is a
+property of the **file**, not of your confidence:
+
+> Every template section carries content or an explicit typed open point, and no section holds an
+> unmarked assumption.
+
+Run `npm run spec:gate <path>` on the spec you just wrote (no path: the whole corpus). It reports the
+missing and the empty sections by name, and it prints what it does **not** check — the unmarked
+assumption is yours to catch, because no parser can. A red gate means the spec is not closed: name
+the section that failed and fix it before step 9.
+
+A gate that has never been seen fail is not known to work, so this one ships with the test that
+watches it fail and pass (`tests/spec-gate.test.js`).
+
 ### Fresh-eyes spec review (step 8, scaled to the dial)
 
 The author's own context is blind to its own gaps — the same mind that wrote the spec self-reviews it
@@ -191,8 +239,12 @@ A returning user on a new device who does not remember a password.
   link can be requested.
 
 ## Points to clarify
-- Link validity window? (assumed: short, exact value deferred to clarify)
-- Rate-limit on requests per email? (deferred)
+- **pregunta abierta** — ¿cuánto vale la ventana de validez del enlace?
+- **suposición tomada** — la ventana es corta, en minutos. *Base:* el patrón de los proveedores que
+  ya usamos. *Riesgo:* si soporte pide horas, cambia el criterio de aceptación.
+- **decisión diferida** — límite de peticiones por email; fuera de este ciclo.
+- **área no formulable** — qué pasa con las cuentas compartidas; sospecho que hay una pregunta y
+  todavía no sé enunciarla.
 ```
 
 Note what is *absent*: no token format, no table, no email provider, no framework. Those are `plan`'s job.
@@ -226,17 +278,16 @@ The proposal is allowed to mention options and tradeoffs; the spec that follows
 
 ## Anti-patterns → STOP
 
+Only failures with no positive statement elsewhere in this skill. The rules about the frontier, the
+constitution, the 2-3 approaches, the gate, and answer-is-not-approval are stated positively above
+(§Questioning discipline, §Detect the moment, the pass, §Approval is its own exchange) and are not
+repeated here as prohibitions: naming a behaviour makes it more available, not less.
+
 | If you're about to… | Reality / Fix |
 | --- | --- |
 | Name a framework, table, endpoint, or library | That's HOW. Strip it; describe the behaviour instead, or log the open question. |
-| Dump 12 questions in one message | One focused question per turn. Infer the rest from the constitution and wiki. |
-| Ask a question you could answer from the constitution | Read it first. Only ask what genuinely changes the spec. |
 | Write "it should work well / be fast / be intuitive" | Not testable. Make it a binary Given/When/Then or move it to Points to clarify. |
-| Skip the whole loop because "this is too simple to design" | That's the rationalization that wastes the most work. Every feature gets the loop; only a literal one-line, zero-risk change skips. |
-| Present one approach as the answer | Offer 2-3 distinct directions with trade-offs and a recommendation; let the user choose before you write the spec. |
 | Hand to `plan`/`implement` before the user approved the written spec | The approval at step 9 is the gate. No design approved → nothing gets built. |
-| Treat the answer to your question as the approval of the spec | They answered the question, and the answer *changed* the spec. Fold it in, say what changed, show it, ask again. |
-| Write `status: aprobada` after a blanket "just run it" | That is autopilot. Record it as such — the record must not overstate the strongest gate in the chain. |
 | Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing. |
 | Resolve every ambiguity yourself to look finished | Inventing answers is worse than naming gaps. List them in Points to clarify. |
 | Start designing the solution because it's clearer | Stay on WHAT/WHY. The plan is a later, separate phase. |
@@ -287,7 +338,7 @@ If `clarify` surfaces answers, they get baked back into this same spec file. Onl
 - `../plan/SKILL.md` — turns the de-risked spec into a technical implementation plan (the HOW).
 - `../harness/SKILL.md` — the 02-DOCS wiki + accompaniment dial + decisions log this skill honors.
 - `references/spec-template.md` — the exact section template written to `02-DOCS/wiki/sdd/specs/<slug>.md`.
-- `references/eliciting-requirements.md` — inference checklist + the one-question-at-a-time elicitation patterns.
+- `references/eliciting-requirements.md` — inference checklist + the frontier-round elicitation pattern.
 
 ## Orientación (siempre)
 

package/skills/specify/evals/cases.yaml

@@ -63,20 +63,20 @@ should_not_trigger:
 capability:
   - scenario: "A user says: 'I want to add magic-link (passwordless) login.' There is a constitution at 02-DOCS/wiki/sdd/constitution.md but no spec yet. Produce the spec."
     must_include:
-      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only scope-changing questions ONE at a time (not a batch of ten)."
+      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only contract-changing gaps — the whole FRONTIER in one numbered round, each with its recommendation, and nothing whose answer depends on another question open in that same round."
       - "Stays strictly WHAT/WHY: no framework, token format, database table, endpoint shape, email provider, library, or file path appears in the spec — implementation-laden answers are flagged as points to clarify instead of guessed."
       - "Produces the spec sections: Problem & why, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify."
       - "Writes testable acceptance criteria in Given/When/Then form that verify could later check (e.g. expired-link refusal, unknown-email revealing nothing)."
       - "Writes the file to 02-DOCS/wiki/sdd/specs/<slug>.md (kebab-case slug), indexes it in the root CLAUDE.md Knowledge map under sdd/specs, and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
-      - "Lists honest Points to clarify (e.g. link validity window, rate-limiting) as the handoff rather than inventing those values."
+      - "Lists honest Points to clarify as the handoff rather than inventing values, and TYPES each one (pregunta abierta / suposición tomada / decisión diferida / área no formulable) so clarify knows whether to ask it, validate it, or leave it alone; a suposición carries its basis."
       - "Ends by pointing to the clarify phase as the next step in the SDD chain."
 
   - scenario: "A user pastes a rough one-liner: 'Let users export all their data as a download.' Show how you'd elicit and capture this without over-asking."
     must_include:
       - "Recovers the underlying problem/why rather than treating the feature request as the problem, and inherits any relevant constraints from the constitution."
-      - "Applies the 'would a different answer change the spec?' test and asks only the genuinely scope-changing question(s), one at a time, in the user's register."
+      - "Applies the 'would a different answer change the contract?' test, then splits what is left by dependency: independent gaps go out together in one round with recommendations, and any gap whose answer hinges on another still-open one is held for the next round rather than asked blind."
       - "Captures observable behaviour (what the user sees/can do) and explicit non-goals / out-of-scope rather than implementation (no file format library, storage, or job-queue detail)."
-      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to Points to clarify instead of fabricating decisions."
+      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to typed Points to clarify instead of fabricating decisions, and checks the written file against the phase's exit gate before calling it done."
       - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
       - "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
       - "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."