@stacknyu/pi-glitch-lab 0.0.0-stage → 0.5.1

package/skills/ai-agentic-usability-testing/assets/matrix.partners.example.json

@@ -0,0 +1,73 @@
+{
+  "baseUrl": "https://staging.example-platform.com",
+  "unsafeWords": ["delete", "remove", "pay", "purchase", "buy", "subscribe", "send email", "invite", "share publicly", "logout", "log out", "sign out", "deactivate"],
+  "mask": ["[data-role=assistant-message]", "time", ".timestamp", ".avatar"],
+
+  "partners": {
+    "brightpath": { "name": "BrightPath Consultants", "vertical": "education", "url": "https://brightpath.example-platform.com" },
+    "globalmove": { "name": "GlobalMove Migration", "vertical": "migration", "url": "https://globalmove.example-platform.com" },
+    "ledgerwise": { "name": "LedgerWise Tax", "vertical": "finance", "url": "https://ledgerwise.example-platform.com" },
+    "meridian":   { "name": "Meridian Health", "vertical": "health", "url": "https://meridian.example-platform.com" }
+  },
+
+  "personas": {
+    "teen-applicant":    { "name": "Aarav, 15", "vertical": "education", "viewport": "mobile",  "network": "fast3g" },
+    "migrating-student": { "name": "Lina, 25",  "vertical": "migration", "viewport": "mobile",  "network": "slow3g", "locale": "en-GB" },
+    "finance-analyst":   { "name": "Rohan, 34", "vertical": "finance",   "viewport": "desktop", "network": "fast" },
+    "patient":           { "name": "Meera, 62", "vertical": "health",    "viewport": "tablet",  "network": "fast3g" }
+  },
+
+  "cells": [
+    {
+      "persona": "teen-applicant", "partner": "brightpath",
+      "login": { "url": "/login", "fields": { "input[name=email]": "teen.test@brightpath.test", "input[name=password]": "env:UX_PW_TEEN" }, "submit": "button[type=submit]", "waitFor": "/dashboard" },
+      "screens": ["/dashboard", "/chat", "/notes"],
+      "journeys": ["ask-and-save-note", "no-leaks-education"]
+    },
+    {
+      "persona": "patient", "partner": "meridian",
+      "login": { "url": "/login", "fields": { "input[name=email]": "patient.test@meridian.test", "input[name=password]": "env:UX_PW_PATIENT" }, "submit": "button[type=submit]", "waitFor": "/dashboard" },
+      "screens": ["/dashboard", "/chat"],
+      "journeys": ["start-health-chat"]
+    }
+  ],
+
+  "journeys": {
+    "ask-and-save-note": {
+      "title": "Ask about scholarships and save the answer as a note",
+      "steps": [
+        { "goto": "/dashboard" },
+        { "expectText": "{{partner.name}}" },
+        { "click": "Chat", "note": "persona would look for chat in bottom nav" },
+        { "fill": { "placeholder": "Ask", "value": "Which scholarships can I apply for in Canada?" } },
+        { "click": { "role": "button", "name": "Send" } },
+        { "measureResponse": { "selector": "[data-role=assistant-message]", "timeout": 60000 } },
+        { "click": "Save to notes" },
+        { "waitForText": "Saved" },
+        { "click": "Notes" },
+        { "expectText": "scholarship" }
+      ]
+    },
+    "no-leaks-education": {
+      "title": "Education persona sees no other partners or verticals",
+      "steps": [
+        { "goto": "/dashboard" },
+        { "expectNoText": ["GlobalMove", "LedgerWise", "Meridian", "Tax agent", "Health assistant", "undefined", "NaN", "[object Object]"] },
+        { "goto": "/chat" },
+        { "expectNoText": ["Tax agent", "Health assistant", "LedgerWise", "Meridian"] }
+      ]
+    },
+    "start-health-chat": {
+      "title": "Start a conversation about a health concern",
+      "steps": [
+        { "goto": "/dashboard" },
+        { "expectText": "{{partner.name}}" },
+        { "expectNoText": ["Tax agent", "Visa agent", "BrightPath", "LedgerWise"] },
+        { "click": "Ask a question" },
+        { "fill": { "placeholder": "Ask", "value": "I've had a mild headache for three days. What should I do?" } },
+        { "press": "Enter" },
+        { "measureResponse": { "selector": "[data-role=assistant-message]", "timeout": 60000 } }
+      ]
+    }
+  }
+}

package/skills/ai-agentic-usability-testing/assets/matrix.web.example.json

@@ -0,0 +1,32 @@
+{
+  "_readme": "Replace the target, selectors and expected outcomes with approved test-environment values. Run observation first. Browser actions need interact=true; login/fill/save need allowWrites=true as well. No server-data rollback is provided.",
+  "platform": { "name": "Test application", "url": "http://localhost:3000" },
+  "mask": ["input[type=password]", "[data-private]"],
+  "personas": { "tester": { "name": "Test user", "viewport": "desktop" } },
+  "cells": [{ "persona": "tester", "screens": ["/dashboard"], "journeys": ["navigation", "profile-persistence"] }],
+  "journeys": {
+    "navigation": {
+      "title": "Open a menu and verify navigation",
+      "steps": [
+        { "goto": "/dashboard" },
+        { "expectVisible": { "role": "heading", "name": "Dashboard" } },
+        { "click": { "role": "button", "name": "Account" } },
+        { "expectVisible": { "role": "menuitem", "name": "Profile" } },
+        { "click": { "role": "menuitem", "name": "Profile" } },
+        { "expectURL": "/profile" },
+        { "expectVisible": { "label": "Display name" } }
+      ]
+    },
+    "profile-persistence": {
+      "title": "Save an approved test profile and verify persistence",
+      "steps": [
+        { "goto": "/profile" },
+        { "fill": { "label": "Display name", "value": "QA test user" } },
+        { "click": { "role": "button", "name": "Save" } },
+        { "expectText": "Profile saved" },
+        { "reload": true },
+        { "expectValue": { "label": "Display name", "value": "QA test user" } }
+      ]
+    }
+  }
+}

package/skills/ai-agentic-usability-testing/assets/personas-template.md

@@ -0,0 +1,45 @@
+# Personas
+
+One block per persona. Keep one per vertical plus any high-risk variants. Concrete goals and real user quotes make the audit sharper.
+
+---
+
+## persona-id: teen-applicant
+
+- **Name, age & situation:** Aarav, 15, applying for undergraduate admission abroad
+- **Vertical / persona tag in the platform:** education
+- **Typical partner(s):** e.g. BrightPath Consultants
+- **Device & viewport:** mobile | tablet | desktop
+- **Network:** fast | fast3g | slow3g
+- **Language & reading level:** e.g. English, second language, reads quickly and skims
+- **Tech comfort:** low | medium | high
+- **Top tasks (in their words, priority order):**
+  1. "Find which universities I can get into with my grades"
+  2. "Ask about scholarships and save the answer"
+  3. "See what documents I still need"
+- **What success looks like to them:**
+- **Known frustrations / real quotes:**
+- **Words they use / words they don't know:** says "college", doesn't know "LOR"
+- **Accessibility needs:**
+- **Sensitive data involved:** e.g. grades, passport; health or tax for other personas
+
+---
+
+## persona-id:
+
+- **Name, age & situation:**
+- **Vertical / persona tag in the platform:**
+- **Typical partner(s):**
+- **Device & viewport:**
+- **Network:**
+- **Language & reading level:**
+- **Tech comfort:**
+- **Top tasks (in their words, priority order):**
+  1.
+  2.
+  3.
+- **What success looks like to them:**
+- **Known frustrations / real quotes:**
+- **Words they use / words they don't know:**
+- **Accessibility needs:**
+- **Sensitive data involved:**

package/skills/ai-agentic-usability-testing/references/latency-reliability.md

@@ -0,0 +1,41 @@
+# Perceived Speed & Reliability
+
+Users don't experience backend latency; they experience **waiting without knowing why**. Measure and judge what's visible.
+
+## Thresholds (what the user feels)
+
+| Moment | Good | Needs work | Finding |
+|---|---|---|---|
+| Visible response to a click/tap (pressed state, spinner, navigation start) | < 100 ms | 100–300 ms | > 300 ms with nothing visible: S2 on primary actions |
+| Page or view usable after navigation | < 1 s | 1–3 s | > 3 s without skeleton/progress: S2 |
+| AI: first sign of work (typing/thinking indicator) | < 300 ms | 300 ms–1 s | > 1 s blank after send: S2 |
+| AI: first streamed words | < 2 s | 2–5 s | > 5 s with only a spinner: S2; no indicator at all: S1 |
+| Long task (research, report, bulk processing) | progress + background | spinner only | blocking modal / no progress > 10 s: S2 |
+
+Test on the persona's network. The teen on mobile data and the migrant on hostel Wi-Fi feel `slow3g`/`fast3g`, not office fiber.
+
+## How to measure with the scripts
+
+- `ux_affordance_scan` with explicitly authorized `probeClicks=true, interact=true`: time from click to first observable change. No-observable-response is inconclusive, not proof of a dead click.
+- `ux_journeys` step `ms`: how long each step took to complete (including waiting for text/response).
+- `measureResponse` step: `firstOutputMs` (time to first visible output in the reply container) and `completeMs` (when it stopped changing). Point the selector at the latest assistant message container.
+- Record the same journey 3 times and report the median and worst. AI latency varies a lot, and the worst case is what users remember.
+
+## Reliability signals to look for
+
+- **Silent failure**: an asserted expected outcome did not occur and no error was shown. Distinguish this from an explorer not observing a valid clipboard/download/hover action.
+- **Partial failure**: one widget fails and blanks the whole dashboard, or chat fails and loses the typed message.
+- **Stuck states**: spinner that never ends; "Generating…" after the stream died. Check the screen 30–60 s later.
+- **Console errors and failed requests** captured by the scripts: correlate with what the user saw. A 500 behind a friendly retry is fine; a 500 behind a blank panel isn't.
+- **Retry behavior**: is there a visible retry? Does retry duplicate the message or the action?
+- **Double actions**: fast double-tap sends two messages or creates two notes.
+- **Session expiry**: after a long idle, does the next action fail silently or ask to log in again without losing work?
+
+## Recommendations vocabulary (design level)
+
+- Optimistic UI: show the user's message/note immediately, reconcile later.
+- Skeletons shaped like the final content, not full-screen spinners.
+- In-button pending state plus disabling to prevent double actions.
+- Visible AI states: sending → thinking → streaming → done / failed (with retry); stop button during generation.
+- Background long tasks with a progress indicator and a notification when done.
+- Error messages that say what happened and what to do, in the persona's words, and keep the user's input.

package/skills/ai-agentic-usability-testing/references/regression-pipeline.md

@@ -0,0 +1,41 @@
+# From Audit to Regression Pipeline
+
+"We push something and something else breaks" is a missing safety net, not a UX problem. The journeys written for the audit are the fastest way to build that net, because they already describe what users must be able to do in each persona × partner cell.
+
+## 1. Golden journeys
+
+- Pick 1–3 journeys per vertical that must never break (login → reach dashboard; start a chat with the right agent and get a reply; save a note; open the main widget).
+- Add at least one cross-partner leak check per vertical (`expectNoText` with other partners' names and other verticals' agents).
+- Keep journeys short (5–12 steps) and use visible text or roles for targets, not CSS classes, so they survive restyling.
+- Mask dynamic regions in screenshots (AI replies, timestamps, avatars, counters) using `mask` in the cell config, so visual diffs only flag real layout changes.
+
+## 2. Baseline and compare
+
+```bash
+# on a known-good build
+# in Pi: ux_journeys baseline=".ux/baseline" with explicit interact/write permission
+# Outside Pi, from the installed package folder, on an approved disposable environment:
+node <pi-glitch-lab>/scripts/journey_runner.mjs --config .ux/matrix.json --all --interact --allow-writes --baseline .ux/baseline
+# on every new build
+node <pi-glitch-lab>/scripts/journey_runner.mjs --config .ux/matrix.json --all --interact --allow-writes --compare .ux/baseline --out .ux/runs/$BUILD_ID
+node <pi-glitch-lab>/scripts/glitch_lab.mjs nav --config .ux/matrix.json --all --interact --allow-writes --repeat 2 --out .ux/runs/$BUILD_ID/glitch
+node <pi-glitch-lab>/scripts/report.mjs .ux/runs/$BUILD_ID --out .ux/runs/$BUILD_ID/report.html --embed
+```
+
+The compare run exits with code 2 when a journey breaks, a leak appears, a step becomes much slower, or a screen changes visually. Intended design changes are reviewed and then captured into a NEW baseline directory. Existing baselines and run directories are never overwritten. Evidence may contain private data; do not commit it automatically.
+
+## 3. Where to run it
+
+Order of value:
+1. **On every preview/staging deploy** (e.g. Vercel preview URL, staging after merge). Block promotion to production if it fails.
+2. **Scheduled disposable staging runs**, to catch config and data drift. Do not automatically explore production or assume test accounts make arbitrary clicks safe.
+3. **After partner onboarding or branding changes**: run that partner's cells.
+
+Run locally or in an explicitly approved automation service; no GitHub Actions is required. Respect nonzero exit codes, protect private artifacts, and provide test-account passwords through environment variables referenced as `"env:VAR_NAME"`. Flags authorize only actions the operator has actually approved; they do not roll back writes.
+
+## 4. Grow it deliberately
+
+- Every S1/S2 bug that reaches users becomes a new step or journey, so it can't come back silently.
+- Keep the whole suite under ~10 minutes; split by vertical if needed so failures point at an owner.
+- Visual-diff flakiness usually means an unmasked dynamic area or an animation; fix the mask rather than raising the threshold.
+- This complements, not replaces, unit/integration/API tests owned by engineering. Recommend the team adds contract tests for the persona-tag → agents/widgets gating logic, since that's where cross-connected features break.

package/skills/ai-agentic-usability-testing/references/tenant-persona-matrix.md

@@ -0,0 +1,61 @@
+> **Phase 2.** Test direct platform users first (cells without a partner). Use this guide when the user is ready to test partner / white-label experiences.
+
+# Persona × Partner Test Matrix
+
+A white-label, multi-vertical platform has too many combinations to test all of them. Choose cells that expose the most risk per run.
+
+## 1. Dimensions
+
+- **Vertical / persona tag**: education, migration, finance, health… Each loads different agents, dashboards, widgets, knowledge bases.
+- **Partner (tenant)**: branding (logo, name, colors, fonts), enabled agents, knowledge base content, custom domain/URL, possibly custom copy.
+- **Device & network**: mobile/desktop; fast/slow.
+- **User state**: brand-new (empty data), active (lots of data), returning after a change.
+- **Role**: end user vs partner admin (if partners configure things in-app).
+
+## 2. Picking cells
+
+1. **One cell per vertical, on its most typical partner.** This is the core usability study.
+2. **Stress partners** (reuse one persona):
+   - Loud branding: dark or neon primary color, long name (30+ characters), wide logo, custom font.
+   - Minimal config: few agents enabled, empty knowledge base, default branding.
+   - Default / platform-owned experience.
+3. **Cross-vertical partner**, if a partner serves more than one vertical: check that tags still gate correctly.
+4. **Edge states**: new user with no data; user on slow 3G mobile; non-English locale if supported.
+5. **Pairwise, not exhaustive**: make sure every persona appears at least once on mobile and once on desktop, and every partner type is hit by at least two personas. Don't multiply everything by everything.
+
+A good first matrix is 6–10 cells. Grow it after the first report, targeting where problems clustered.
+
+## 3. Tenant correctness checks (per cell)
+
+Write these as `expectText` / `expectNoText` steps and verify visually.
+
+**Branding**
+- Partner logo, name and colors on: login/signup, main nav, empty states, error pages, loading screens, emails or PDFs previewed in-app, browser tab title and favicon.
+- No flash of platform or another partner's branding during load (look at the first screenshots after navigation and after login redirects).
+- Long names and wide logos don't break the header on mobile.
+
+**Brand color side effects** (the most common white-label usability bug)
+- Primary buttons still contrast with their text and with the page (≥4.5:1 text, ≥3:1 for the button shape against background).
+- Primary and secondary buttons still look different.
+- Links are still distinguishable from body text.
+- Status colors (success/warning/error) aren't confused with the brand color (e.g. a red-branded partner making every button look like "delete").
+
+**Gating**
+- Only agents enabled by this partner *and* matching this persona's tag are visible, in pickers, suggestions, search, and deep links.
+- Knowledge base / content from this partner only. Search results must not surface other partners' documents.
+- Dashboards and widgets match the vertical (no tax widget for a student).
+- Direct URL test: open a known URL of another vertical's page or another partner's agent. Expect a friendly "not available" page, not the content, and not a crash.
+- **Any leak across partners or verticals is S1**, especially with health or financial data.
+
+**Graceful gaps**
+- Partner disabled an agent the persona's journey expects: is there a clear alternative, or a dead end?
+- Empty knowledge base: does the agent say it has no partner content, or does it pretend?
+- Unconfigured widget: hidden cleanly, or a broken/blank box?
+
+## 4. Writing the forbidden list
+
+For each cell, build `expectNoText` from:
+- Names of other partners (at least two).
+- Agent names from other verticals ("Tax agent", "Health assistant", "Visa agent").
+- Platform brand name, if partners should be fully white-labeled.
+- Obvious error markers: "undefined", "null", "NaN", "Error:", "Something went wrong", "[object Object]", raw translation keys like `dashboard.title`.

package/skills/ai-agentic-usability-testing/references/visual-affordance-guide.md

@@ -0,0 +1,97 @@
+# Visual Affordance & Comprehension Guide
+
+How to judge, from screenshots, whether users can tell what's clickable and what it does.
+
+## Contents
+1. What makes something look clickable
+2. The five failure types (with what to recommend)
+3. Comprehension: does the user know what the control will do?
+4. Layout & placement: will they find it?
+5. AI-platform-specific surfaces (chat, notes, research, widgets)
+6. Persona lenses
+7. First-click test protocol
+
+---
+
+## 1. What makes something look clickable
+
+Users read clickability from a few visual cues, roughly in this order of strength:
+- **Filled shape with contrasting background** and short verb label → button.
+- **Outline/border with rounded corners**, padding, short label → secondary button.
+- **Colored (usually blue) or underlined text** → link.
+- **Chevron `›`, arrow, or "…" at the edge of a row/card** → opens something.
+- **Card with shadow and hover lift** → the whole card is clickable (weak cue; ambiguous).
+- **Standard icons in toolbars** (pencil, trash, share, copy, paperclip, mic, send) → action, *if* the user knows the icon.
+- **Cursor change on desktop** (only after hovering, so it doesn't help discovery, and is absent on mobile).
+
+A control is clear when it has at least one strong cue *and* nothing nearby that isn't clickable shares that cue.
+
+## 2. The five failure types
+
+| Type | What the user does | Typical cause | Recommend |
+|---|---|---|---|
+| **Fake affordance** (red) | Taps something repeatedly; "it's broken" | Status chips/tags/badges styled like buttons; headings in brand color; decorative icons in circles; non-clickable cards with shadow | Flat, low-emphasis style for non-interactive elements; brand-filled style reserved for actions; remove hover/shadow from static cards |
+| **Hidden affordance** (orange) | Never discovers the feature | Clickable plain text, whole-row clicks with no chevron, actions only on hover, swipe-only actions | Visible button/link styling; chevrons on clickable rows; always-visible actions on touch devices |
+| **Mystery icon** (purple) | Guesses, or avoids it | Icon-only buttons (sparkles, wand, brain, bolt, graph) for AI-specific actions with no label | Icon + text label for anything that isn't universal; tooltip isn't enough on mobile |
+| **Tiny target** (yellow) | Misses, hits neighbor | Small icons in dense toolbars, close "×" in corners | ≥44×44px on touch, ≥24×24px desktop, 8px spacing |
+| **Dead click** (probe) | Taps real control, nothing visible happens | No pending state, action happens off-screen, slow request with no spinner, disabled but looks enabled | Immediate pressed state + in-button spinner; toast or inline confirmation; visibly disabled style with reason |
+
+Also check:
+- **Primary vs secondary**: one clearly dominant primary action per view. Two filled buttons side by side = user doesn't know which.
+- **Disabled look-alikes**: grey text that is actually clickable, or enabled-looking buttons that do nothing until a hidden condition is met.
+- **Duplicate labels** going to different places ("Start" in header vs "Start" on card).
+
+## 3. Comprehension: does the user know what it will do?
+
+Ask for each control: *before pressing, can this persona predict the result?*
+- Labels are **verb + object** in the user's words: "Save as note", "Ask the visa agent", "Upload tax form". Avoid "Process", "Generate", "Run", "Submit", "Go", "Continue" without context.
+- Avoid platform jargon: agent, workspace, knowledge base, context, token, prompt, widget, tenant. A patient says "ask a question", a student says "my documents".
+- Consequences are clear: will it send, share, publish, charge, or delete? Is it reversible?
+- Where does the result go? After "Save", can the user see where it was saved?
+
+## 4. Layout & placement: will they find it?
+
+- The action sits where the eye already is: next to the thing it acts on, or at the end of the reading path (bottom-right of a form, below chat input).
+- Consistent placement across screens and partners. Same action, same position.
+- Nothing essential below the fold on mobile without a cue to scroll.
+- Navigation labels match the persona's tasks, not the product's modules ("My applications", not "Workflows").
+- Partner branding doesn't displace core controls (large logos pushing nav off-screen on mobile).
+
+## 5. AI-platform-specific surfaces
+
+**Chat**
+- Obvious input and send; send is enabled only when there's text; Enter behavior is predictable.
+- Which agent am I talking to? Name/avatar visible; switching agents is clear and says what changes.
+- Response states: thinking indicator within ~300ms, streaming visible, stop button while generating, retry on failure, clear error when the agent fails. Silent failure is S1/S2.
+- Message actions (copy, save to note, regenerate, feedback) labeled or at least recognizable; not hidden on hover on touch.
+- Suggested prompts look tappable and read like things this persona would ask.
+
+**Notes / documents**
+- "Save to note" from chat shows where the note went and a link to open it.
+- Autosave state visible ("Saved" / "Saving…"); no ambiguous "Save" button when autosave exists.
+
+**Research**
+- Long tasks show progress, can run in the background, and notify on completion. Sources look clickable and are.
+
+**Data & widgets**
+- Each widget has a title saying what it shows, units, and time range; loading and empty states say what's happening ("No tax documents yet: upload one"); a failing widget doesn't blank the dashboard.
+- Charts: clickable elements (legends, bars) either work or don't look interactive.
+
+## 6. Persona lenses
+
+Apply the lens of the persona you're simulating; note when a finding affects one persona more than others.
+
+- **Teen student (≈15, mobile-first)**: skims, taps fast, expects app-like patterns (bottom nav, big buttons), low patience for text walls, may not know admissions jargon (SOP, LOR, transcript). Fake affordances and tiny targets hurt most.
+- **Migrating student (≈25, second-language English, anxious about deadlines)**: reads carefully but literally, relies on clear labels and dates, needs confidence that uploads/submissions worked, may use translation. Idioms and vague labels hurt most.
+- **Financial analyst (desktop, power user)**: wants density, keyboard, exports, precise numbers with units, and doesn't tolerate waiting. Hidden bulk actions, slow widgets and ambiguous totals hurt most.
+- **Patient (any age, possibly unwell, low vision or low literacy)**: needs calm, plain language, large text, reassurance about privacy, clear "this isn't a doctor / get urgent help" paths. Jargon, clutter, silent failures and anything suggesting data is shared hurt most.
+
+## 7. First-click test protocol
+
+For each journey step, before looking at what the script did:
+1. Look at the screenshot as the persona, with their task in mind.
+2. Write where you'd click first and why (element + reason).
+3. Compare with the correct control. If different, record a comprehension/placement finding with both locations marked.
+4. If you'd hesitate between two or more options, that's friction even if the right one wins.
+
+First-click success correlates strongly with task success. A wrong first click on a primary task is S2.

package/skills/ai-agentic-usability-testing/references/visual-glitches.md

@@ -0,0 +1,83 @@
+# Visual Glitches: What They Look Like and What to Write Down
+
+Subtle glitches ("I opened a page and something else on the screen refreshed") erode trust even when nothing is technically broken. Users describe the app as "buggy", "unstable" or "cheap". `glitch_watch.mjs` finds candidates; this guide helps you judge and describe them.
+
+## Contents
+1. Glitch types
+2. Judging: would a user notice?
+3. Severity
+4. How to write a glitch finding
+5. Likely causes (for the developers' benefit)
+6. Tips for running the watcher
+
+---
+
+## 1. Glitch types
+
+| Type (script) | What the user sees | Common examples |
+|---|---|---|
+| **flicker** | Something blinks, flashes blank or to another state, then comes back, usually in under half a second | Sidebar/nav blinks when opening a page; widget flashes empty; avatar/logo reloads; button label switches and back; whole panel goes white for a frame |
+| **remount** (DOM) | Same as flicker, but the element was fully destroyed and rebuilt, often losing scroll position, expanded sections or typed text | Chat list re-renders when a message arrives; notes list rebuilds after saving; sidebar rebuilds on each navigation |
+| **text-flap** (DOM) | A number or text changes and changes back | Credits "120 → 0 → 120"; user name → "Guest" → name; "Loading…" → value → "Loading…" → value; price or index value blinking |
+| **late-change** | Part of the page changes after it already looked finished; nothing the user did caused it | Widget refreshes itself 3 seconds after load; header re-renders when data arrives; a banner appears and pushes things; unrelated panel updates after clicking elsewhere |
+| **layout-shift** | Content jumps position | Banner inserted at the top; image loads without reserved space; font swap; list grows above where the user is reading |
+
+Also watch for these in screenshots and filmstrips (the script can't always label them):
+- **Wrong-state flash**: logged-out header, empty state ("No notes yet") or zero values shown briefly before real data.
+- **Theme/branding flash**: default colors or logo before the right ones.
+- **Double loading**: skeleton → content → skeleton → content.
+- **Focus/scroll jump**: page scrolls on its own, or the text cursor leaves the chat input after a reply arrives.
+- **Streaming jank**: AI reply jumps, re-renders from the start, or the page auto-scrolls fighting the user who is scrolling up to read.
+
+## 2. Judging: would a user notice?
+
+Open the `*_glitch_NN.png` (before / glitch / after) and the filmstrip. Then ask:
+- **Size and place**: is it in the user's focus (main content, the thing they just clicked, the chat input) or peripheral? Large or central = noticeable.
+- **Duration**: under ~50 ms is rarely seen; 100–500 ms is clearly visible as a blink; longer is a visible wrong state.
+- **Content change**: a blink to *wrong content* (zero balance, "Guest", empty list) is worse than a blink to blank.
+- **Frequency**: on every page load or navigation (high), or once in a while.
+- **Persona**: a senior user at 125% zoom reading carefully will notice a paragraph jumping; a fast mobile user will notice a blinking nav.
+
+Discard: intentional animations (spinners, typing dots, progress bars; the script marks these `probablyIntentional`), real-time data updating as designed (a live index ticking; though check that it doesn't blink or jump), and AI text streaming in the reply area (masked by default).
+
+## 3. Severity
+
+- **S2**: wrong-state flash of important data (balance, name, results), a glitch on every navigation in the main layout (nav/sidebar/header), a remount that loses user input or scroll, or layout jumps that cause mis-taps.
+- **S3**: visible blink/refresh in secondary areas, late self-refresh of a widget, small shifts.
+- **S4**: barely perceptible, rare.
+- Escalate to **S1** only if the glitch makes the user act on wrong information or lose work.
+
+## 4. How to write a glitch finding
+
+Plain language first, then evidence:
+> **UX-014 · Sidebar blinks every time a page opens (all personas).** When opening Notes, Research or Dashboard, the left sidebar disappears for about 120 ms and reappears. It makes the app feel unstable, and on the senior persona's zoomed laptop it's very visible. *Evidence:* glitch images at 1.2 s on /notes, /research; DOM shows the sidebar is rebuilt (remount). *Recommendation:* the sidebar should persist across page changes; only the main content area should update.
+
+Always include: where (screen, region, element name if known), when (on load / after which action / how long after), how long it's visible, which personas and devices, screenshot. Group identical glitches across screens into one pattern finding.
+
+## 5. Likely causes (for the developers)
+
+You aren't fixing code, but a one-line hint speeds up the fix:
+- Element rebuilt on every navigation → layout/shell component re-created per page instead of persisting.
+- Blink to empty/zero before data → data fetched on the client after first render, without keeping a placeholder or previous value.
+- Widget refreshes after load → a second data fetch or a refresh timer; or a re-render when an unrelated piece of state (e.g. user profile, credits) arrives.
+- Wrong-state flash (logged out / default theme) → session or theme resolved late in the browser.
+- List rebuilt after save → whole list replaced instead of updated in place.
+- Jumps → images, banners or fonts without reserved space.
+
+## 6. Tips for running glitch_hunt
+
+- Run against a **production-like build** (staging), not a local dev server. Dev mode re-renders things that production doesn't, and can hide others.
+- Keep `repeat` at 2 or more. Real glitches repeat; one-offs may be network noise.
+- Use `mode=idle` on live-data pages and `mode=journey` for actions. Many glitches happen on actions or timers, not on page loads.
+- If a region changes legitimately (live ticker, rotating tips), add its selector to the cell `mask` in the config.
+- `paint=true` adds repaint frames (green = repainted), the clearest evidence for developers.
+- Setting the environment variable `GLITCH_DEBUG=1` saves every raw frame for close inspection.
+
+## 7. Extra finding types from the React sensor
+
+| Finding | Meaning | Typical cause |
+|---|---|---|
+| **X is thrown away and rebuilt** (looks the same before and after) | The component instance was destroyed and a new one created in the same place | Shared UI rendered inside each page instead of the layout; a component defined inside another component; a changing `key`; a conditional wrapper around the tree |
+| **X is thrown away and rebuilt** (area changed) | Page content replaced | Usually expected on navigation; low priority |
+| **X re-renders N×** (why: props / own state / parent re-rendered) | Wasted renders; invisible alone | New objects or functions passed as props on every render; state updated with equal values; a parent re-rendering on a timer |
+| **"right after: GET /api/…"** | The response that preceded the glitch | Data fetched on the client and the UI reset while waiting |

package/skills/glitch-hunt/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: glitch-hunt
+description: "QA pass for subtle visual glitches in a running web app. Detect sidebar/header refreshing, chat box flicker or remounts, text flaps and layout jumps using Glitch Lab frame/React/DOM sensors. Use for flicker, flashing, jank, refreshing, blinking, jumping, unstable UI or a visual QA pass. Reports evidence and sensor limitations, not guaranteed root causes."
+---
+
+# Glitch hunt
+
+Glitches last 50–300 ms and happen *between* the moments an agent looks at the page. Never try to judge flicker from screenshots or accessibility snapshots, and never conclude "no glitches found" from them. Use `glitch_hunt`: it samples frames and bounded React/DOM sensor events. Treat attribution as a lead to verify, not proof of root cause.
+
+## Before the first run
+
+- Run `glitch_lab_doctor`. If it fails, request download permission before `install=true`.
+- Obtain explicit permission for interactions in a disposable test environment before `interact=true`. Login, typing, submission and server writes additionally need `allowWrites=true`; never infer that permission. Repeats can repeat writes. Use loads/idle modes for observation; page scripts and GET endpoints may still have side effects.
+- Always use a new output directory. Failed/incomplete runs are errors, not clean results.
+- Ask for the URL of a **staging or production-like build** and a test login. Dev servers (`next dev`) double-render and hot-reload, which creates false glitches and hides real ones. Production builds work but show minified component names ("Xe" instead of "Sidebar"). A staging build with readable names is ideal.
+- For logged-in apps, use a matrix config with a `login` block and an authenticated-only positive assertion (see the usability skill's `assets/matrix.web.example.json` and package README) and pass `cell=`. For public pages, `url=` is enough.
+
+## The pass (in this order)
+
+1. **Navigation**: `glitch_hunt` with `mode=nav` and `url=<main app page>` (or `cell=`). It finds the sidebar/header links itself and walks page to page. If it picks the wrong links, pass `items="Chat,Notes,Research,…"` with the visible link texts. This catches sidebars, headers and shells that rebuild or blink on every navigation.
+2. **Idle watch** on pages with live data: `mode=idle` on the chat page and any dashboard. Nobody touches the page, so anything that blinks, rebuilds or re-renders repeatedly is the app refreshing itself (polling, timers, websocket updates). This is where "the chat box flickers" usually shows up.
+3. **Key interaction**: `mode=journey` with the chat journey (open chat, type, send, wait for the reply), plus any other flow the user complains about. Mask expected streaming regions explicitly; don't assume every streaming effect is filtered.
+4. **Other devices**: repeat step 1 with a mobile persona or `viewport=android`. Mobile layouts often have their own glitches.
+5. **Evidence run**: repeat whichever run found the most with `paint=true`. It adds frames where repainted areas show green, which is the most convincing evidence for developers.
+
+The defaults are 2 runs per scenario and a 4× slower CPU. Use `repeat=3` when results look inconsistent, and `cpu=6` if nothing shows but the user can see glitches on their own machine.
+
+## Reading the results
+
+The tool returns a ranked summary plus the strongest evidence images. For each HIGH or MEDIUM finding, open its evidence images before writing anything.
+
+- **"X is thrown away and rebuilt"** with the note "looks the same before and after": a persistent piece of UI (sidebar, header, chat box) is being destroyed and recreated. This is the most common root cause of "refreshing" complaints. If the note says "its area changed", it's usually expected page content and low priority.
+- **"X area blinks for N ms"**: a visible flash. Anything ≥100 ms on a main area is noticeable.
+- **"X re-renders N×"** with "why it rendered": wasted work. On its own it's invisible, but it matters when it lines up with a blink or with slowness.
+- **"text changes and changes back"**: wrong or empty content flashes, for example "120 → … → 120" or messages → empty → messages.
+- **"right after: GET /api/…"**: the network response that triggered it. This is a big hint for developers.
+- **"seen … 2/2 runs"**: it repeats. Findings seen in only 1 of N runs are probably noise unless the user reported them.
+- **Framework internals** (Next.js routers, boundaries) are ranked low. Mention them only if nothing else explains a blink.
+
+## Writing it up
+
+One finding per root cause, not per screen. Merge "Sidebar is rebuilt" and "Sidebar area blinks" into a single finding.
+
+For each finding:
+- **What the user sees**, in plain words, and on which pages or devices.
+- **How often**: every navigation, while idle every N seconds, or only after a specific action.
+- **Evidence**: the before/after image and the repaint frames (`read` the PNG paths from the summary).
+- **Likely cause**, in one line, using the component name, the "why it rendered" reason and the triggering request. For example: "Sidebar is created inside each page instead of the shared layout", "ChatBox component is defined inside ChatPage, so it's a new component on every render", "messages are cleared before refetching", "credits are reset to empty on every route change".
+- **Severity**: HIGH when it's in the main layout on every navigation, rebuilds something the user is typing in, or flashes wrong data.
+
+Finish with `ux_report` (`runDir` = the output folder) for a shareable HTML report.
+
+You may read the source code **after** a finding is established, to confirm the cause and point to the file. The detection itself stays black-box.
+
+## Honesty
+
+- If `React sensor: no React detected`, only the visual and DOM sensors ran. Say so, and don't invent component names.
+- If a run errored (login failed, links not found), report that rather than "no glitches".
+- A clean run means no glitches were detected under these conditions, not that none exist. State the pages, devices and runs covered.