@damiangilgonzalez/harness 1.3.7

package/skills/monitoring/references/burn-rate-and-oncall.md

@@ -0,0 +1,128 @@
+# Burn-rate alerting and on-call
+
+The full math behind the SLO table in SKILL.md, plus copy-paste alert rules, escalation, and a runbook template.
+
+## What "burn rate" means
+
+Pick an SLO, e.g. **99.9% availability over 30 days**. The **error budget** is the allowed bad fraction: `1 - 0.999 = 0.1%` of requests over the month.
+
+**Burn rate = how many times faster than "even" you are spending that budget.**
+
+- Burn rate `1` = you'd exactly exhaust the 30-day budget in 30 days. Fine.
+- Burn rate `14.4` = you'd exhaust the *entire month's* budget in `30d / 14.4 ≈ 2h`. Page now.
+
+Why 14.4: it is the rate that burns **2% of the monthly budget in 1 hour** — the Google SRE workbook's recommended fast-burn page threshold. The other rows: **6×** burns ~5% in 6h (ticket), **1×** burns ~10% in 3d (slow review).
+
+## Why two windows
+
+A single window either pages on a momentary spike (short window alone) or reacts too slowly (long window alone). **Require a long AND a short window to both exceed the burn threshold:**
+
+- The **long window** confirms the burn is sustained ("this is real").
+- The **short window** confirms it's still happening right now ("don't page me for an outage that already ended"). It also gives fast reset once you recover.
+
+This combination is what kills false positives.
+
+## Prometheus-style alert rule
+
+Symptom-based, two windows, with a `runbook_url` annotation. Adjust `job`/`code` to your metric names.
+
+```yaml
+groups:
+  - name: slo-burn-rate
+    rules:
+      # CRITICAL — page. Fast burn: 14.4x over 1h, confirmed by a 5m short window.
+      - alert: CheckoutErrorBudgetFastBurn
+        expr: |
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[1h]))
+            / sum(rate(http_requests_total{job="checkout"}[1h]))
+          ) > (14.4 * 0.001)
+          and
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[5m]))
+            / sum(rate(http_requests_total{job="checkout"}[5m]))
+          ) > (14.4 * 0.001)
+        labels:
+          severity: critical        # routes to page
+        annotations:
+          summary: "Checkout burning error budget 14.4x (1h+5m)"
+          runbook_url: "https://wiki.example.com/runbooks/checkout-5xx"
+
+      # WARNING — ticket. Slower burn: 6x over 6h, confirmed by a 30m short window.
+      - alert: CheckoutErrorBudgetSlowBurn
+        expr: |
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[6h]))
+            / sum(rate(http_requests_total{job="checkout"}[6h]))
+          ) > (6 * 0.001)
+          and
+          (
+            sum(rate(http_requests_total{job="checkout",code=~"5.."}[30m]))
+            / sum(rate(http_requests_total{job="checkout"}[30m]))
+          ) > (6 * 0.001)
+        labels:
+          severity: warning          # routes to ticket
+        annotations:
+          summary: "Checkout slow error-budget burn (6h+30m)"
+          runbook_url: "https://wiki.example.com/runbooks/checkout-5xx"
+```
+
+Note: every alert carries `runbook_url`, and the rule is a *ratio* (symptom), never a bare `cpu`/`memory` threshold.
+
+## Severity → routing
+
+| Label | Where it goes | Who acts | When |
+|---|---|---|---|
+| `critical` | PagerDuty/Better Stack page → escalation policy | on-call, now | immediately, any hour |
+| `warning` | ticket queue / Slack channel | team | next business hours |
+| `info` | dashboard / weekly review | nobody paged | retro |
+
+## Escalation policy (sample)
+
+```yaml
+# Vendor-agnostic shape — maps to PagerDuty / incident.io / Better Stack.
+escalation_policy:
+  name: checkout-oncall
+  on_call:
+    primary:   "@oncall-primary"     # weekly rotation
+    secondary: "@oncall-secondary"   # weekly rotation, offset
+  steps:
+    - notify: primary
+      ack_timeout_minutes: 10        # no ack -> escalate
+    - notify: secondary
+      ack_timeout_minutes: 10
+    - notify: "@eng-manager"
+  repeat_until_acked: true
+  resolve_notifies: true             # send the all-clear too
+# Do NOT build this on Opsgenie (EOL 2027-04-05) or Grafana OnCall OSS (deprecated).
+```
+
+## Runbook template
+
+Every alert's `runbook_url` points to one of these. Fill it in before the alert ships, not at 3am.
+
+```markdown
+# Runbook: <alert name>
+
+## Symptom
+What the alert literally measures (e.g. "checkout 5xx ratio > 14.4x SLO burn, 1h+5m").
+
+## Impact
+What the user experiences (e.g. "checkout failing → lost revenue, ~X orders/min").
+
+## First 3 checks
+1. Dashboard link: <url> — is it errors or latency?
+2. Recent deploys: <link> — did we ship in the last 30 min? Consider rollback (see ../deployment/SKILL.md).
+3. Dependency status: DB / cache / payment provider status pages.
+
+## Mitigation
+- Fastest safe action (rollback / feature-flag off / scale out — see ../scaling/SKILL.md).
+- Holding action if root cause unknown (drain region, enable degraded mode).
+
+## Escalation
+- If not mitigated in 15 min, page secondary and open an incident.
+- Post to the public status page; notify #incidents.
+
+## Dashboards
+- <links to the relevant observability dashboards — see ../observability/SKILL.md>
+```

package/skills/monitoring/references/tool-setup.md

@@ -0,0 +1,154 @@
+# Tool setup
+
+Concrete, copy-pasteable configs. Pricing/versions as of 2026-06.
+
+## Uptime Kuma (self-hosted, free)
+
+`docker-compose.yml` — rootless image, persistent volume, single port.
+
+```yaml
+services:
+  uptime-kuma:
+    image: louislam/uptime-kuma:2.1.3-rootless
+    container_name: uptime-kuma
+    restart: unless-stopped
+    volumes:
+      - kuma-data:/app/data
+    ports:
+      - "3001:3001"
+volumes:
+  kuma-data:
+```
+
+```bash
+docker compose up -d
+# open http://your-vps:3001, create the admin user on first load,
+# then put it behind your reverse proxy with TLS (do not expose 3001 raw).
+```
+
+Monitors to add (Kuma calls them "Monitor type"):
+
+- **HTTP(s)** on your critical endpoint — set "Accepted status codes" to `200-299`, interval 60s, retries 3, and enable **Globalping** (Kuma 2.1) to probe from multiple regions instead of just the box.
+- **HTTP(s) – Keyword** to assert a string in the body (e.g. a logged-in marker), so a 200 that renders an error page still alerts.
+- **Push** (heartbeat) for a cron/worker: the job `curl`s a Kuma push URL each run; if the beat is missed, Kuma pages. This catches *silent* batch failures.
+- **TLS expiry**: enable "Certificate Expiry Notification" on the HTTP monitor; notify at 14 days.
+- **Domain expiry**: Kuma 2.1 has a domain-expiry monitor type; notify at 30 days.
+
+```bash
+# Push-heartbeat from a cron job — alert fires if this stops arriving.
+*/5 * * * * /usr/bin/curl -fsS "https://kuma.example.com/api/push/AbC123?status=up&msg=ok" >/dev/null
+```
+
+## Notification wiring
+
+Kuma has 90+ channels; here are the three you actually use.
+
+```bash
+# ntfy — dead-simple push to your phone, self-hostable, free.
+# In Kuma: Settings → Notifications → ntfy. Server https://ntfy.sh, topic = a long random string.
+curl -d "checkout 5xx > 2%" ntfy.sh/your-long-random-topic   # test it lands
+```
+
+```json
+// Slack incoming webhook — paste the webhook URL into Kuma's Slack notification.
+{ "text": "🔴 [PAGE] checkout error rate 4.1% (>2% for 5m) — runbook: https://wiki/runbooks/checkout-5xx" }
+```
+
+```text
+# PagerDuty — use Events API v2. In PagerDuty create a service → integration
+# "Events API v2" → copy the Integration Key (routing key) into Kuma's PagerDuty
+# notification. Critical severity routes to the on-call escalation policy.
+Integration Key: R0UT1NGK3Yxxxxxxxxxxxxxxxxxxxxxxx
+Severity:        critical   # so it pages, not just logs
+```
+
+## Managed alternative — monitor config shape
+
+UptimeRobot / Better Stack store this server-side; the shape you reason about:
+
+```json
+{
+  "type": "http",
+  "url": "https://api.example.com/readyz",
+  "method": "GET",
+  "expected_status": 200,
+  "interval_seconds": 60,
+  "regions": ["eu", "us-east", "ap"],
+  "assertions": [
+    { "type": "status_code", "comparison": "equals", "target": 200 },
+    { "type": "response_time", "comparison": "less_than", "target_ms": 800 },
+    { "type": "body", "comparison": "contains", "target": "\"status\":\"ready\"" }
+  ],
+  "ssl_expiry_alert_days": 14,
+  "domain_expiry_alert_days": 30,
+  "on_failure": { "after_failures": 2, "notify": ["pagerduty-critical"] }
+}
+```
+
+## Synthetic critical-journey check
+
+Not just `GET /` — exercise the path that earns money. Shape of a multi-step synthetic:
+
+```yaml
+# synthetic: login -> add to cart -> checkout. Run every 5 min from 2+ regions.
+name: checkout-journey
+steps:
+  - POST /api/login        { body: { user: "$SYNTH_USER", pass: "$SYNTH_PASS" }, expect: 200 }
+  - POST /api/cart         { body: { sku: "TEST-SKU", qty: 1 }, expect: 200, save: cart_id }
+  - POST /api/checkout     { body: { cart: "$cart_id", token: "tok_test" }, expect: 200 }
+assert:
+  - total_duration_ms < 4000
+on_fail: page   # this is real user impact
+```
+
+## Health-endpoint handlers
+
+### FastAPI (Python)
+
+```python
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+@app.get("/livez")           # liveness: process only. Orchestrator restarts on fail.
+def livez():
+    return {"status": "alive"}
+
+@app.get("/readyz")          # readiness: deps with short timeouts. LB pulls instance on fail.
+async def readyz():
+    checks = {
+        "db": await ping_db(timeout=0.2),
+        "cache": await ping_cache(timeout=0.1),
+    }
+    ready = all(checks.values())
+    return JSONResponse(
+        {"status": "ready" if ready else "degraded", "checks": checks},
+        status_code=200 if ready else 503,
+    )
+```
+
+### Go
+
+```go
+// Liveness: process only, ~instant. Never touch the DB here.
+http.HandleFunc("/livez", func(w http.ResponseWriter, r *http.Request) {
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(http.StatusOK)
+    _, _ = w.Write([]byte(`{"status":"alive"}`))
+})
+
+// Readiness: deps with a tight deadline so the probe stays cheap (<100ms).
+http.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {
+    ctx, cancel := context.WithTimeout(r.Context(), 200*time.Millisecond)
+    defer cancel()
+    w.Header().Set("Content-Type", "application/json")
+    if err := db.PingContext(ctx); err != nil {
+        w.WriteHeader(http.StatusServiceUnavailable) // 503 -> LB pulls this instance
+        _, _ = w.Write([]byte(`{"status":"degraded","checks":{"db":false}}`))
+        return
+    }
+    w.WriteHeader(http.StatusOK)
+    _, _ = w.Write([]byte(`{"status":"ready","checks":{"db":true}}`))
+})
+```

package/skills/monitoring/scripts/verify.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# verify.sh — monitoring config sanity gate. Read-only. Run inside YOUR project or
+# point it at a monitoring config/spec dir or file. CI runs the same file (parity).
+#
+# Usage:
+#   bash scripts/verify.sh [PATH]    # PATH defaults to "."
+#
+# What it checks, against the load-bearing rules of the monitoring skill:
+#   1. Discover candidate monitoring files (alert rules, health specs, monitor configs).
+#      No candidates -> nothing to gate -> exit 0 (clean target is never a failure).
+#   2. Health endpoints separate liveness from readiness (livez/liveness AND readyz/readiness).
+#   3. At least one alert is symptom/SLO/burn-rate based with TWO windows — FAIL only if
+#      alert rules exist and the ONLY thresholds are bare cpu/memory.
+#   4. Every alert block carries a runbook reference (runbook / runbook_url).
+#   5. Banlist: Opsgenie introduced as a NEW setup; a monitor whose only target is "/".
+#
+# Dependency-light: bash + grep + find only. Portable to macOS bash 3.2 and CI bash 5.
+# Read-only: never writes, never mutates. Exits nonzero only on a real FAIL.
+#
+# Env: NO_COLOR=1 to disable color.
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [[ -n "${NO_COLOR:-}" ]]; then YEL=""; GRN=""; RED=""; RST=""
+else YEL=$'\033[33m'; GRN=$'\033[32m'; RED=$'\033[31m'; RST=$'\033[0m'; fi
+ok()   { printf '%sPASS:%s %s\n' "$GRN" "$RST" "$*"; }
+fail() { printf '%sFAIL:%s %s\n' "$RED" "$RST" "$*"; }
+skip() { printf '%sSKIP:%s %s\n' "$YEL" "$RST" "$*"; }
+
+FAILED=0
+
+# 1. discover candidate files. bash-3.2-safe (no mapfile); NUL-delimited for spaces.
+FILES=()
+if [[ -f "$TARGET" ]]; then
+  FILES+=("$TARGET")
+elif [[ -d "$TARGET" ]]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$TARGET" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' \) -prune \
+    -o -type f \( -name '*.yml' -o -name '*.yaml' -o -name '*.json' \
+       -o -name '*.rules' -o -name '*.conf' -o -name '*.md' \) -print0 2>/dev/null)
+else
+  skip "target not found: $TARGET — nothing to gate"; exit 0
+fi
+
+# Keep only files that look like monitoring artifacts (alerts/health/monitors).
+CAND=()
+for f in ${FILES[@]+"${FILES[@]}"}; do
+  if grep -liE 'alert|burn[_-]?rate|livez|readyz|liveness|readiness|monitor|uptime|escalation|runbook' "$f" >/dev/null 2>&1; then
+    CAND+=("$f")
+  fi
+done
+
+if [[ ${#CAND[@]} -eq 0 ]]; then
+  printf 'No monitoring config/spec files found under %s — nothing to gate.\n' "$TARGET"
+  exit 0
+fi
+
+# Build a single haystack of the candidate contents for cross-file checks.
+HAY="$(cat ${CAND[@]+"${CAND[@]}"} 2>/dev/null || true)"
+
+# Helpers (case-insensitive grep against the haystack).
+has() { printf '%s' "$HAY" | grep -qiE "$1"; }
+
+# 2. liveness vs readiness — only meaningful if a health spec is present at all.
+if printf '%s' "$HAY" | grep -qiE 'livez|liveness|readyz|readiness|health'; then
+  if has 'livez|liveness' && has 'readyz|readiness'; then
+    ok "health spec separates liveness from readiness"
+  else
+    fail "health spec does not separate liveness (/livez) from readiness (/readyz)"
+    FAILED=1
+  fi
+else
+  skip "no health-endpoint spec present — liveness/readiness check not applicable"
+fi
+
+# 3. symptom/SLO/burn-rate alert with two windows.
+if has 'alert|expr|burn|rate\(|error[_ ]?rate|severity'; then
+  TWO_WINDOW=0
+  # burn-rate keyword, or an explicit long+short pairing of distinct time windows.
+  if has 'burn[_-]?rate|multi[_-]?window'; then TWO_WINDOW=1; fi
+  if printf '%s' "$HAY" | grep -qE '\[(1h|6h|3d|24h)\]' \
+     && printf '%s' "$HAY" | grep -qE '\[(5m|30m|6h)\]'; then TWO_WINDOW=1; fi
+  if has '(long|short)[ _-]?window'; then TWO_WINDOW=1; fi
+
+  # Are the ONLY thresholds bare cpu/memory? (cause-based, no symptom alert).
+  ONLY_CAUSE=0
+  if has 'cpu|memory|mem_usage|load average' \
+     && ! has 'error[_ ]?rate|5\.\.|5xx|latency|p9[59]|burn|availability|uptime'; then
+    ONLY_CAUSE=1
+  fi
+
+  if [[ $ONLY_CAUSE -eq 1 ]]; then
+    fail "only cause-based thresholds found (cpu/memory) — add a symptom/SLO alert"
+    FAILED=1
+  elif [[ $TWO_WINDOW -eq 1 ]]; then
+    ok "symptom/SLO alert with two windows (burn-rate or long+short) present"
+  else
+    fail "alert present but no two-window/burn-rate symptom alert — single-window 'by vibes'"
+    FAILED=1
+  fi
+
+  # 4. runbook reference on alerts.
+  if has 'runbook'; then
+    ok "alerts reference a runbook"
+  else
+    fail "alert rules carry no runbook/runbook_url reference"
+    FAILED=1
+  fi
+else
+  skip "no alert rules present — alert/runbook checks not applicable"
+fi
+
+# 5a. banlist — Opsgenie as a NEW setup (EOL 2027-04-05).
+# Allow mentions that are clearly a do-NOT note; flag a bare adoption.
+if has 'opsgenie'; then
+  if printf '%s' "$HAY" | grep -iE 'opsgenie' | grep -qiE "do not|don't|deprecat|eol|retir|avoid|instead of|not start|no usar|migrat"; then
+    ok "opsgenie referenced only as a do-not/deprecation note"
+  else
+    fail "opsgenie configured as a new setup — it is EOL 2027-04-05; use PagerDuty/incident.io/Better Stack/Grafana Cloud IRM"
+    FAILED=1
+  fi
+fi
+
+# 5b. banlist — a monitor whose only target is the homepage "/".
+# Flag url:"/" or path "/" used as a probe target with no critical-journey/readyz target.
+if printf '%s' "$HAY" | grep -qE '(url|path|target|target_url)["'"'"' :]+["'"'"']?/["'"'"']?\s*$' \
+   || printf '%s' "$HAY" | grep -qE '(url|path|target)["'"'"' :]+["'"'"']/["'"'"']'; then
+  if has 'readyz|/api/|journey|checkout|login|critical'; then
+    ok "homepage probe present but a deeper/critical-journey target also configured"
+  else
+    fail "monitor target appears to be homepage '/' only — probe the critical user journey, not just /"
+    FAILED=1
+  fi
+fi
+
+# summary
+if [[ $FAILED -eq 0 ]]; then
+  ok "all monitoring checks passed (skips are not failures)"
+else
+  fail "one or more monitoring checks failed"
+fi
+exit "$FAILED"

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