free-pi-cli 0.6.2 → 0.6.4

package/skills/ux-walker/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: ux-walker
+description: Walk a UX story catalog (docs/ux-paths/catalog.md) through a real browser one story at a time, checking each journey for correctness, visual quality and UX. Looks at screenshots with look_at_image, measures alignment, spacing and wrapping with a geometry audit, and logs flow friction. Fixes small issues and writes up larger ones.
+---
+
+# UX Walker
+
+Walk each story in the catalog through a real browser. For every story, check that the
+journey works, that the screens look right, and that the path is as short and clear as
+it should be. Fix small problems on the spot. Write up larger ones.
+
+This skill runs on your default model. Do not switch to a more expensive model. You
+cannot see images directly: judge screenshots with the `look_at_image` tool (a cheap
+vision model), and use DOM measurements for anything that can be measured.
+
+Everything runs in one agent, in order. Walk one story, write its files, keep a
+one-line summary in your head, then start the next. Do not try to hold several stories
+in context. After a context reset, resume from the files in `docs/ux-walker/`.
+
+## When to use
+
+"walk the stories", "test the ux paths", "ux walker", "verify user journeys", "qa the
+user flows". Needs a catalog at `docs/ux-paths/catalog.md` (made by the ux-paths skill).
+
+Options the user may give: a URL, `--full` (re-walk everything), `--focus <topic>`
+(only that topic), `--session <name>` (reuse a browser session, keeps login). With no
+arguments, detect the URL and start. Ask only if the app needs a login and you have no
+test credentials.
+
+`$SKILL_DIR` below means the folder that contains this SKILL.md.
+
+## Output
+
+```
+docs/ux-walker/
+  run-history.json        state across runs
+  walk-plan.json          plan for the current run
+  latest-report.md        final report
+  issues-filed.md         every issue written up
+  issues/<finding-id>.md  issue files when gh is not available
+  shots/STORY-NNN/        screenshots (must stay inside the project folder)
+  stories/STORY-NNN/walk-report.md   what happened at each step
+  stories/STORY-NNN/findings.json    findings for the story
+  fixes/<finding-id>.md   one note per quick fix
+```
+
+Screenshots must be saved inside the project folder, or look_at_image refuses them.
+
+## Step 0: Preflight
+
+1. **Browser tool.** `command -v agent-browser`. If missing, use `npx -y agent-browser`
+   everywhere below instead. On first use run `agent-browser install` (or
+   `npx -y agent-browser install`) once. Command patterns: `references/action-patterns.md`.
+2. **URL.** `curl -s -o /dev/null -w "%{http_code}" <url>`. If nothing answers, find the
+   dev command in package.json (or the README), start it in the background with a log
+   and a saved PID (`nohup <cmd> > docs/ux-walker/dev.log 2>&1 & echo $! > docs/ux-walker/dev.pid`),
+   pick a free port, wait for it once, and stop only that PID at the end. If you saved browser login state, delete `"${TMPDIR:-/tmp}/free-pi-ux-browser-state.json"` too.
+3. **Catalog.** If `docs/ux-paths/catalog.md` is missing, stop and tell the user to run
+   the ux-paths skill first.
+4. **Folders.** `mkdir -p docs/ux-walker/stories docs/ux-walker/shots docs/ux-walker/fixes`. Before a story's
+   first screenshot, also run `mkdir -p docs/ux-walker/shots/STORY-NNN` (agent-browser does not create it).
+5. **Run history.** Load `docs/ux-walker/run-history.json`, or start with
+   `{"runs": [], "stories": {}}`. Each story entry: `last_walked`, `status`
+   (pass or fail), `findings_count`, `source_files_hash`, `fixes_merged_since`.
+6. **Session.** Use `S=ux-walker-<domain>` (or the user's `--session`). Open the app:
+   `agent-browser --session $S open <url>` then `agent-browser --session $S wait --load networkidle`
+   (for apps with live connections, wait for a known element instead).
+7. **Version check (optional).** `curl -s <url>/__version` or `<url>/version.json`. If it
+   returns a git SHA that differs from `git rev-parse --short HEAD`, note that you may
+   be testing an older build and continue.
+
+## Step 1: Plan the walk
+
+Read the catalog once. Write `docs/ux-walker/walk-plan.json` with one entry per story:
+`{id, action, reason}`. Decide each action:
+
+- `--full`: all stories are `walk`. `--focus topic`: only matching stories.
+- Never walked: `walk`.
+- Passed before and relevant source files unchanged since (`git log --since` on the
+  files the story touches, or compare `source_files_hash`): `skip`.
+- Passed before but source changed: `re-verify`.
+- Failed before and fixes made since: `re-verify`. Failed with no fixes: `walk`.
+
+Tell the user the counts (walk, re-verify, skip), then start.
+
+## Step 2: Walk the stories, one at a time
+
+Read `references/ux-audit-rubric.md` and `references/visual-inspection.md` once before
+the first story. For each story in the plan, in order:
+
+### 2a. Walk
+
+A story in the catalog has: Type, Topic, Persona, Goal, Preconditions, Steps,
+Variations, Edge Cases, and sometimes an Ideal path. Use these fields as written.
+
+For each step:
+1. `agent-browser --session $S snapshot -i`, find the target by text or role, act
+   (`click @e3`, `fill @e2 "..."`, `open <url>`). See `references/action-patterns.md`.
+2. Screenshot into `docs/ux-walker/shots/STORY-NNN/step-N.png`.
+3. Check the step's expected result from the snapshot or `get text` / `get url`.
+4. At each **distinct page state** (a new page or a major layout change, not every
+   click): run the geometry audit, then make one look_at_image call (below).
+5. Check `agent-browser --session $S errors` now and then. Console errors and failed
+   requests often explain visible problems.
+
+**Geometry audit** (measure first):
+```bash
+agent-browser --session $S eval --stdin < "$SKILL_DIR/references/geometry-audit.js"
+```
+It reports uneven sibling rows, overflow spills, wrapped controls and page horizontal
+overflow. Confirm each hit before logging it.
+
+**look_at_image** (one call per distinct page state, one specific question):
+```
+look_at_image(path="docs/ux-walker/shots/STORY-007/step-3.png",
+  question="<the look-pass question from references/visual-inspection.md, trimmed to this screen>")
+```
+Each call uses part of the user's daily allowance. Do not call it for every step, do
+not ask about the same image twice, and do not use it to measure. The answer comes
+from another model and can be wrong: check any layout claim with `get box` or the
+geometry audit before you log it.
+
+**Responsive spot-check**, once per story at its main screen (skip for desktop-only
+apps): `set viewport 390 844`, screenshot, run the geometry audit, `set viewport 1280 800`.
+Only spend a look_at_image call if the audit reports something or the page looks odd.
+
+**Audit the page state** against `references/ux-audit-rubric.md`: simplicity,
+progressive disclosure, layout, visual correctness and consistency, hierarchy (one
+clear primary action, nothing said twice), typography, feedback, error states, text
+fit, accessibility basics. Ask "what could be removed without losing function?"
+
+**Flow log** (write it as the last section of walk-report.md):
+- Steps the story specified versus steps you actually needed. If the catalog has an
+  Ideal path and you needed more steps, log a `flow` finding naming the friction.
+- Each moment the persona would hesitate (control not found in the first snapshot,
+  ambiguous label, unexpected navigation): a discoverability finding.
+- Data the user re-enters that the app already knows: a `flow` finding.
+- Information or controls shown on more than one screen: note it in the log.
+
+If a step fails (element missing, unexpected state): screenshot, record the failure,
+try to recover (back, reload), continue the remaining steps, and mark the story `fail`.
+
+For an interaction bug that a still image cannot show, record a short video:
+`record start docs/ux-walker/shots/STORY-NNN/finding-N.webm`, repeat the steps with
+`wait 1000` between them, `record stop`. For a static bug one screenshot is enough.
+
+### 2b. Write the files now
+
+Before starting the next story, write:
+- `stories/STORY-NNN/walk-report.md`: for each distinct screen, one sentence on what the
+  screenshot shows plus the geometry result ("clean" or the hits); end with the flow log.
+- `stories/STORY-NNN/findings.json`: array of objects:
+  ```json
+  {"id": "F-007-001", "story_id": "STORY-007",
+   "severity": "critical|high|medium|low|suggestion",
+   "category": "simplicity|disclosure|layout|visual|consistency|hierarchy|flow|happy-path|a11y|error-handling",
+   "criterion": "which check failed", "score": "warn|fail",
+   "description": "", "expected": "", "actual": "",
+   "screenshot": "shots/STORY-007/finding-1.png",
+   "suggested_fix": "or null", "files_likely_involved": ["src/Foo.tsx"]}
+  ```
+- Update the story's entry in `run-history.json`.
+
+Every finding needs at least a screenshot path, and a measurement when the problem is
+visual ("left edges differ by 7px"). Stories are a script, not a limit: log anything
+else you notice. Do not read source code while walking. Read it only when you fix.
+
+Keep only a one-line summary of the story in context ("STORY-007 fail, 3 findings:
+1 high, 2 low"), then triage that story's findings and move on.
+
+### 2c. Triage
+
+Use `references/triage-rubric.md`. A finding is a **quick fix** only if it touches 2 or
+fewer files, has an obvious fix, is low risk, and is medium severity or lower. Critical
+and high findings, anything needing design thought, and anything touching 3 or more
+files are written up as issues. Suggestions are only listed in the report. At most 10
+quick fixes per run.
+
+### 2d. Fix (one at a time)
+
+For each quick fix, in order:
+1. Read the relevant source files. Make the smallest change that resolves the finding.
+   Only edit files inside the project folder; if the page is served from somewhere else, write the
+   fix up as an issue instead.
+   No refactoring, no nearby "improvements".
+2. Run the project's build, type check or the nearest test (look in package.json).
+3. Commit only the files you changed, with `fix(ux): <finding-id> <short description>`.
+   Never `git add -A`. Work on the current branch unless the user says otherwise; if it
+   is the default branch, create a branch first. Do not push.
+4. Write `docs/ux-walker/fixes/<finding-id>.md`: what was wrong, what changed, build result.
+5. Re-check the fix in the browser (reload, repeat the step, run the geometry audit,
+   take a new screenshot). If it persists, revert your change and write it up as an issue.
+
+If a fix breaks the build and you cannot repair it quickly, revert it and write an issue.
+
+### 2e. Write up larger issues
+
+For each finding that is not a quick fix, use `references/issue-template.md`.
+
+- If `command -v gh` succeeds and `gh auth status` passes: `gh issue create` with the
+  filled template (`--label ux-walker`; add other labels only if they exist).
+- Otherwise save the filled template to `docs/ux-walker/issues/<finding-id>.md`.
+
+Add a row to `docs/ux-walker/issues-filed.md`: issue (number or file), story, severity,
+title, URL or path.
+
+## Step 3: Re-walk fixed stories
+
+After all stories are done, re-walk only the steps that had fixed findings, one story at
+a time, with a fresh screenshot and audit. Mark the story `pass` if all findings are
+resolved, otherwise `fail` and note what remains. Update `run-history.json` with the
+run totals (stories walked, skipped, re-verified, findings, fixes, issues, passed, failed).
+
+## Step 4: Report
+
+Read the story files one at a time and build `docs/ux-walker/latest-report.md` from
+`templates/latest-report-template.md`. Include:
+
+1. Run metadata (date, URL, session, counts).
+2. Findings by severity and by category.
+3. Quick fixes applied (finding, files, verified or not).
+4. Issues filed or saved (with paths or URLs).
+5. UX audit summary: patterns across stories and systemic issues. The same audit defect
+   on several screens is one systemic finding.
+6. Flow friction table (story, actual versus ideal steps, hesitations) and information
+   shown in more than one place. If flow or redundancy shows up in 3 or more stories,
+   recommend running the ux-flow skill.
+7. Top 5 recommendations.
+8. Stories still failing, with reasons.
+
+Finish with a short summary to the user: stories walked, pass and fail counts, fixes
+made (with commit SHAs), issues written, and the path to the report. State plainly
+what you did not verify.
+
+## Error handling
+
+| Situation | Action |
+|-----------|--------|
+| agent-browser cannot connect | Retry once. Run `agent-browser install` if the browser is missing. If it still fails, tell the user. |
+| Step fails | Screenshot, recover, continue, mark the story `fail`. |
+| look_at_image returns an error (daily allowance, rate limit) | Do not retry in a loop. Rely on the geometry audit and the snapshot for the rest of the run, say so in the report, and tell the user. |
+| Fix breaks the build | Revert it and write an issue. |
+| Catalog missing | Stop. Ask the user to run the ux-paths skill. |
+| Nothing to walk | Report that all stories pass with no source changes. Suggest `--full`. |
+
+## Rules
+
+- Never delete screenshots, videos or reports during a run.
+- Use test accounts and test data only. Do not click destructive actions against real data.
+- Write each story's files before starting the next story.
+- Do not push, and do not merge to the default branch.

package/skills/ux-walker/references/action-patterns.md

@@ -0,0 +1,75 @@
+# Action patterns: story step to agent-browser command
+
+All commands run through bash. Use `agent-browser --session $S <command>`.
+Run `agent-browser <command> --help` if unsure; do not guess flags.
+
+## Core loop
+
+1. `snapshot -i` lists interactive elements with refs such as `@e3`.
+2. Act on a ref (or a CSS selector).
+3. Take a screenshot into the project folder.
+4. Verify the expected result (re-run `snapshot -i`, or `get text`, `get url`).
+
+Refs go stale after navigation or large page changes. Take a fresh snapshot then.
+
+## Actions
+
+| Story step | Command |
+|---|---|
+| Go to a URL | `agent-browser --session $S open <url>` |
+| Back / forward / reload | `back`, `forward`, `reload` |
+| Click a ref | `click @e3` |
+| Click by visible text (no snapshot yet) | `find text "Sign in" click` |
+| Click by role and name | `find role button --name "Save" click` |
+| Type character by character | `type @e2 "hello"` |
+| Replace a field value | `fill @e2 "hello"` |
+| Fill by label | `find label "Email" fill "a@b.test"` |
+| Choose a dropdown option | `select @e4 "Option A"` |
+| Check / uncheck | `check @e5`, `uncheck @e5` |
+| Press a key | `press Enter`, `press Escape`, `press Tab` |
+| Hover | `hover @e6` |
+| Scroll | `scroll down 400`, `scrollintoview @e7` |
+| Wait for page | `wait --load networkidle` (live apps with websockets never go idle; use the next line) |
+| Wait for text or element | `wait --text "Saved"`, `wait "#results"`, `wait 800` (ms) |
+| Current URL / title | `get url`, `get title` |
+| Element text | `get text @e3` |
+| Element size and position | `get box <selector>` |
+| Computed styles | `get styles <selector>` |
+| Console errors | `errors`, `console` |
+| Screenshot (viewport) | `screenshot docs/ux-walker/shots/<story>/step-1.png` |
+| Screenshot (whole page) | `screenshot --full <path>` |
+| Numbered labels on controls | `screenshot --annotate <path>` |
+| Narrow / wide viewport | `set viewport 390 844`, `set viewport 1280 800` |
+| Dark mode | `set media dark`, `set media light` |
+| Save / restore login | `state save "${TMPDIR:-/tmp}/free-pi-ux-browser-state.json"`, `state load "${TMPDIR:-/tmp}/free-pi-ux-browser-state.json"` (kept outside the project because it holds cookies; never commit it; delete it at the end of the run) |
+| Video of an interaction | `record start docs/ux-walker/shots/<story>/f1.webm`, act with `wait 1000` between steps, `record stop` |
+
+Several commands can go in one bash call, joined with `&&`.
+
+## Run the audit script
+
+```bash
+agent-browser --session $S eval --stdin < "$SKILL_DIR/references/geometry-audit.js"
+```
+
+`$SKILL_DIR` is the folder that contains this skill's SKILL.md.
+
+## Common flows
+
+Login: `snapshot -i`, `fill @e1 "<user>"`, `fill @e2 "<password>"`, `click @e3`,
+`wait --load networkidle`, screenshot, then `state save` to the path above. Use only test accounts that
+the project provides. Never type real credentials from the user's environment.
+
+Modal: click the trigger, `wait 500`, `snapshot -i` (the modal is now in the tree),
+screenshot, act, `snapshot -i` again to confirm it closed.
+
+Form: `snapshot -i`, `fill` each field by ref, submit, `wait --text "<success text>"`.
+
+Drag: `drag @e1 @e2`, then screenshot.
+
+## Pacing and recovery
+
+- `wait 500` after clicks that animate; `wait 1000` after navigation or submit.
+- If an action fails: screenshot, `snapshot -i`, then try once more (scroll into
+  view, wait, fresh snapshot). If it fails twice, log the failure and go to the next step.
+- If `agent-browser` cannot start, run `npx -y agent-browser install` once and retry.

package/skills/ux-walker/references/geometry-audit.js

@@ -0,0 +1,82 @@
+// Geometry audit — run via: agent-browser --session {S} eval "$(cat geometry-audit.js)"
+// Returns JSON of measurable layout defects. Numbers beat eyeballs for evenness;
+// use the screenshot to judge whether a reported violation actually matters.
+(() => {
+  const sig = (e) => {
+    let s = e.tagName.toLowerCase();
+    if (e.id) s += '#' + e.id;
+    else if (typeof e.className === 'string' && e.className.trim())
+      s += '.' + e.className.trim().split(/\s+/).slice(0, 2).join('.');
+    const t = (e.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 30);
+    return t ? s + ' "' + t + '"' : s;
+  };
+  const vis = (e) => {
+    const r = e.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) return false;
+    const cs = getComputedStyle(e);
+    return cs.visibility !== 'hidden' && cs.display !== 'none';
+  };
+  const firstClass = (e) =>
+    typeof e.className === 'string' ? (e.className.trim().split(/\s+/)[0] || '') : '';
+
+  const out = {
+    pageOverflowX: Math.max(0, document.documentElement.scrollWidth - window.innerWidth),
+    unevenRows: [],      // similar siblings in one visual row with different shapes/gaps
+    overflowSpills: [],  // content escaping its container
+    wrappedControls: [], // short button/tab/chip labels forced onto 2+ lines
+  };
+
+  // 1. Sibling uniformity: flex-row/grid containers whose children are structurally
+  //    similar (same tag + first class) should share height, width, gap, and top edge.
+  for (const p of document.querySelectorAll('body *')) {
+    const cs = getComputedStyle(p);
+    const flexRow = cs.display.includes('flex') && cs.flexDirection.startsWith('row');
+    const grid = cs.display.includes('grid');
+    if (!flexRow && !grid) continue;
+    const kids = [...p.children].filter(vis);
+    if (kids.length < 2 || kids.length > 16) continue;
+    if (!kids.every((k) => k.tagName === kids[0].tagName && firstClass(k) === firstClass(kids[0]))) continue;
+    const rects = kids.map((k) => k.getBoundingClientRect());
+    const topDrift = Math.max(...rects.map((r) => r.top)) - Math.min(...rects.map((r) => r.top));
+    if (topDrift > 24) continue; // wrapped onto multiple rows — not one visual row
+    const hs = rects.map((r) => Math.round(r.height));
+    const ws = rects.map((r) => Math.round(r.width));
+    const sorted = [...rects].sort((a, b) => a.left - b.left);
+    const gaps = [];
+    for (let i = 1; i < sorted.length; i++) gaps.push(Math.round(sorted[i].left - sorted[i - 1].right));
+    const issue = {};
+    if (Math.max(...hs) - Math.min(...hs) > 8) issue.heights = hs;
+    if (flexRow && Math.max(...ws) - Math.min(...ws) > 8) issue.widths = ws;
+    if (gaps.length > 1 && Math.max(...gaps) - Math.min(...gaps) > 4) issue.gaps = gaps;
+    if (topDrift > 3) issue.topDriftPx = Math.round(topDrift);
+    if (Object.keys(issue).length)
+      out.unevenRows.push({ container: sig(p), children: kids.length, ...issue });
+  }
+
+  // 2. Overflow: element content wider than its box while overflow-x is visible.
+  for (const e of document.querySelectorAll('body *')) {
+    if (!vis(e) || e.clientWidth < 24) continue;
+    if (!getComputedStyle(e).overflowX.includes('visible')) continue;
+    if (e.scrollWidth > e.clientWidth + 4)
+      out.overflowSpills.push({ el: sig(e), spillPx: e.scrollWidth - e.clientWidth });
+  }
+
+  // 3. Wrapped controls: a short label on a block-ish control taking 2+ lines
+  //    means the container is too narrow or the label too long for the layout.
+  for (const b of document.querySelectorAll('button, [role="button"], a, summary, [class*="tab"], [class*="chip"], [class*="badge"]')) {
+    if (!vis(b)) continue;
+    const cs = getComputedStyle(b);
+    if (cs.display === 'inline') continue; // prose links legitimately wrap
+    if (b.querySelector('br, svg, img')) continue;
+    const label = (b.textContent || '').trim();
+    if (!label || label.length > 40) continue;
+    const lh = parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.4;
+    const contentH = b.clientHeight - parseFloat(cs.paddingTop) - parseFloat(cs.paddingBottom);
+    if (contentH > lh * 1.8) out.wrappedControls.push(sig(b));
+  }
+
+  for (const k of ['unevenRows', 'overflowSpills', 'wrappedControls']) {
+    if (out[k].length > 12) { out[k] = out[k].slice(0, 12); out[k + 'Truncated'] = true; }
+  }
+  return JSON.stringify(out);
+})();

package/skills/ux-walker/references/issue-template.md

@@ -0,0 +1,110 @@
+# GitHub Issue Template — UX Walker Findings
+
+Use this for findings the triage rubric sends to an issue. File with `gh issue create` only if `gh` is installed and authenticated; otherwise save the filled template to `docs/ux-walker/issues/{FINDING_ID}.md`.
+
+## Template
+
+```markdown
+## Context
+
+Found by ux-walker during **STORY-{STORY_ID}: "{STORY_TITLE}"**
+- **Run date**: {ISO_DATE}
+- **Step**: Step {STEP_NUMBER} — "{STEP_DESCRIPTION}"
+- **URL at time of finding**: {CURRENT_URL}
+
+## Finding
+
+**ID**: {FINDING_ID}
+**Severity**: {SEVERITY}
+**Category**: {CATEGORY}
+**Rubric Criterion**: {CRITERION} ({SCORE})
+
+### Description
+{DETAILED_DESCRIPTION}
+
+### Expected Behavior
+{EXPECTED}
+
+### Actual Behavior
+{ACTUAL}
+
+## Evidence
+
+### Screenshot
+<!-- Attach or reference the screenshot -->
+![{FINDING_ID}]({SCREENSHOT_PATH})
+
+### Page Snapshot (if relevant)
+<details>
+<summary>Accessibility tree at time of finding</summary>
+
+```
+{SNAPSHOT_EXCERPT}
+```
+
+</details>
+
+## Suggested Approach
+
+{SUGGESTED_FIX_OR_APPROACH}
+
+### Files Likely Involved
+{FILES_LIST — bulleted list of file paths}
+
+### Estimated Complexity
+- **Files to change**: {FILE_COUNT}
+- **Regression risk**: {LOW|MEDIUM|HIGH}
+- **Design input needed**: {YES|NO}
+
+## Related
+
+- **Story**: STORY-{STORY_ID} in `docs/ux-paths/catalog.md`
+- **Walk report**: `docs/ux-walker/stories/STORY-{STORY_ID}/walk-report.md`
+- **Full findings**: `docs/ux-walker/stories/STORY-{STORY_ID}/findings.json`
+
+---
+Filed by ux-walker
+```
+
+## Usage — gh CLI Command
+
+```bash
+gh issue create \
+  --title "UX: {SHORT_DESCRIPTION}" \
+  --body "$(cat <<'EOF'
+{FILLED_TEMPLATE}
+EOF
+)" \
+  --label "ux-walker"
+```
+
+## Field Reference
+
+| Field | Source | Example |
+|-------|--------|---------|
+| `STORY_ID` | walk-plan.json | `STORY-014` |
+| `STORY_TITLE` | catalog.md | `New user creates first workspace` |
+| `ISO_DATE` | Current timestamp | `2026-03-20T14:30:00Z` |
+| `STEP_NUMBER` | findings.json → step | `3` |
+| `STEP_DESCRIPTION` | catalog.md step text | `Click "Create Workspace" button` |
+| `CURRENT_URL` | agent-browser url output | `http://localhost:1420/workspaces` |
+| `FINDING_ID` | findings.json → id | `F-014-003` |
+| `SEVERITY` | findings.json → severity | `high` |
+| `CATEGORY` | findings.json → category | `layout` |
+| `CRITERION` | findings.json → criterion | `Viewport usage` |
+| `SCORE` | findings.json → score | `fail` |
+| `DETAILED_DESCRIPTION` | findings.json → description | Full narrative |
+| `EXPECTED` | findings.json → expected | What should happen |
+| `ACTUAL` | findings.json → actual | What actually happens |
+| `SCREENSHOT_PATH` | findings.json → screenshot | Relative path |
+| `SNAPSHOT_EXCERPT` | Saved snapshot output | Trimmed to relevant section |
+| `SUGGESTED_FIX_OR_APPROACH` | findings.json → suggested_fix | Or "Needs design discussion" |
+| `FILES_LIST` | findings.json → files_likely_involved | Bulleted paths |
+| `FILE_COUNT` | Derived from files list | `4` |
+
+## Notes
+
+- Keep issue titles under 70 characters
+- Title format: `UX: {verb} {what}` — e.g., "UX: simplify workspace creation form"
+- If no suggested approach is obvious, write "Needs design discussion — the current implementation {description of problem}."
+- Always include the screenshot — it's the most valuable part for async review

package/skills/ux-walker/references/triage-rubric.md

@@ -0,0 +1,55 @@
+# Triage rubric: quick fix or written issue
+
+Decide for each finding after a story is walked.
+
+## Quick fix: ALL must be true
+
+1. Touches 2 or fewer source files.
+2. The fix is obvious (typo, CSS tweak, missing label, wrong color, spacing).
+3. Low regression risk.
+4. Can be done in under 15 minutes.
+5. Severity is medium or lower.
+
+Examples: typo in a button; padding off by a few pixels; missing label or aria-label;
+text overflow in one component; missing hover style; sibling cards with uneven
+heights (`align-items: stretch`); wrapped button label (`white-space: nowrap`);
+uneven gaps (use `gap`); inconsistent border radius.
+
+## Write an issue: ANY is true
+
+- Touches 3 or more files.
+- Needs design thought or changes a workflow or information structure.
+- Could break other features.
+- Severity is critical or high.
+- Restructures components or changes state handling.
+- Needs a feature that does not exist.
+
+Examples: confusing navigation; a 15-field form that should be progressive; raw API
+errors shown to users; missing loading states across the app; broken mobile layout;
+no keyboard support.
+
+## Overrides
+
+- Critical findings are always written up, even if the fix looks easy.
+- Suggestions are never fixed or filed. They go in the report only.
+- At most 10 quick fixes per run. Further findings become issues (a sign of a
+  systemic problem).
+
+## Checklist
+
+```
+1. Severity medium or lower?          no -> issue
+2. 2 files or fewer?                  no -> issue
+3. Solution obvious?                  no -> issue
+4. Low regression risk?               no -> issue
+5. Fewer than 10 quick fixes so far?  no -> issue
+All yes -> quick fix
+```
+
+## Where issues go
+
+If `command -v gh` finds GitHub CLI and `gh auth status` succeeds, file with
+`gh issue create` (see issue-template.md). Otherwise write each issue as a markdown
+file in `docs/ux-walker/issues/<finding-id>.md` using the same template, and list them
+in `docs/ux-walker/issues-filed.md`. Labels: `ux-walker` plus the severity; add other
+labels only if they already exist in the repo.