/ux-grill

name: ux-grill
user-invocable: true
argument-hint: "[url | manifest-path]"
description: Use when a running web app's UX has to be audited reproducibly rather than by feel — a deterministic mechanical pass over routes and viewports (axe, target size, horizontal overflow, page title, scripted journeys) followed by a screenshot-grounded interrogation of the operator, journey by journey, with two persona lenses from the target repo's manifest. Triggered by "grill the UX", "roast the dashboard", "UX-Audit", "/ux-grill". Bootstraps its own manifest from a loopback URL on the first run, so it never requires a hand-written file to start.
model: inherit
color: magenta
tools: Read, Grep, Glob, Bash, Write

UX-Grill Skill

> Two stages, hard boundary. **Stufe 1** measures — a Node pass over routes × viewports that calls `agent-browser` and writes JSON, with no model in the loop. **Stufe 2** grills — the `/grill` loop applied to journeys, where every claim carries a screenshot path. Severity is never a judgment here; it comes out of `schema.mjs`.

Invocation

The user invoked `/ux-grill` with arguments: **$ARGUMENTS**. Parse them before anything else — exactly one positional argument is recognised:

• **An absolute `http(s)` URL** (e.g. `http://127.0.0.1:3100`) → bootstrap path (§ 0.2). The target repo has no manifest yet; ask for the env names, crawl the navigation and write one. The URL must be loopback — anything else is refused before a browser starts.
• **A file path** (ends in `.md`, or resolves to an existing file) → treat it as the manifest path, repo-relative to the target repo.
• **Empty** → the manifest at `DEFAULT_MANIFEST_PATH` (`.orchestrator/ux-manifest.md` <!-- path-check: example -->). If that file does not exist, say so and name the bootstrap form `/ux-grill <url>` — do not invent a manifest from nothing.
• **Anything else** → stop with: `ux-grill: argument must be a loopback URL or a manifest path (default .orchestrator/ux-manifest.md)`.

Examples:

• `/ux-grill` — runs against the target repo's existing manifest
• `/ux-grill http://127.0.0.1:3100` — first run: AUQ for env names, crawl, write the manifest, stop with a fill-in hint
• `/ux-grill .orchestrator/ux-manifest.md` — explicit manifest path

**No CI, no HARD-GATE.** Stufe 1 is built CI-shaped (deterministic, exit-coded, LLM-free) but is deliberately not wired into any pipeline — the PRD's dose argument. `/ux-grill` gates nothing: it writes measurement artefacts, an optional dossier and — only through `reconcile.mjs` <!-- path-check: planned #1327 --> — issues. It never commits, never pushes, never edits product code.

Soul Reference

Read `soul.md` in this skill directory before anything else. It defines WHO you are — the UX Interrogator — the persona-lens discipline, and the six tactics in their UX form. The rubric you measure against is `rubric-v2.md`; read it before Phase 1 so you can read `findings.jsonl` without guessing what a `checkId` means.

When to use

• A web app is running on loopback and the operator wants its UX improved systematically, not by single impressions
• The same audit has to be re-runnable later, so that "did this get better?" is answerable by fingerprint diff rather than memory
• Mobile and desktop need judging against the SAME journeys, with the viewport verified rather than assumed
• Journeys exist (or can be written) as executable `agent-browser` command lines

When NOT to use

• A CI-shaped end-to-end run over an existing test profile → `/test` (driver + `agents/ux-evaluator.md`). `ux-evaluator` is deliberately NOT reused here: Stufe 1 is LLM-free by construction.
• A plan, PRD or design needs stress-testing before it is built → `/grill`. There is no running app to measure yet.
• Per-wave design drift against the design source → `design-reviewer` (SO#1300 B4). That checks whether the built thing matches the design; `/ux-grill` checks whether a person gets through the journey.
• A native macOS app → out of scope in v2; web only.
• A non-loopback target → refused, not degraded. Both `loadManifest()` and `collect()` assert it.

Phase 0: Target + Stufe 1

0.1 Resolve the argument

Per § Invocation above: a loopback URL selects the bootstrap path, a file path or empty selects `DEFAULT_MANIFEST_PATH` from `scripts/lib/ux-grill/manifest.mjs`.

0.2 Bootstrap (URL, no manifest yet)

This path exists because the predecessor skill died of its absence: a tool that presupposes a hand-written manifest is never started.

1. **Ask ONCE, up to three questions in a single `AskUserQuestion` call** — the env FILE name and the two login env NAMES. Never a value; the manifest and everything downstream carry names only.

AskUserQuestion({
  questions: [
    { question: "Which env file of the target repo holds the login credentials?",
      header: "Env-Datei",
      options: [
        { label: ".env.local (Recommended)", description: "The usual dev file. Cost: none — only the NAME is stored; values stay in the gitignored file." },
        { label: ".env.e2e.local", description: "A separate e2e file, where one exists. Same storage contract." },
        { label: "Ohne Login", description: "No credentials at all — personas stay empty and only the unauthenticated navigation is crawled. Cost: journeys behind the login are invisible." },
        { label: "Other / describe below", description: "Name a different file." } ],
      multiSelect: false },
    { question: "Which env variable holds the login e-mail?",
      header: "Mail-Env",
      options: [
        { label: "TEST_USER_EMAIL (Recommended)", description: "The most common name in the env file you picked. Cost: none — the NAME is stored, the value never is." },
        { label: "LOGIN_EMAIL", description: "Use when the target repo names it that way." },
        { label: "Other / describe below", description: "Name the variable yourself; read it from the env file first." } ],
      multiSelect: false },
    { question: "Which env