visual-qa

What it does

Verifies a rendered UI against intent using objective script evidence plus two parallel read-only oracle passes, then synthesizes a single good/bad verdict. It handles web/page UIs and TUI/terminal UIs, capturing reference and actual evidence, computing diffs, and triggering dual-pass QA reviews.

How it works

• Step 1 - Detect the surface: determine whether the UI is web/page-based or a TUI, and identify if a reference packet exists for pixel-accurate comparison.
• Step 2 - Capture objective reference evidence: generate or ingest a reference packet (screenshots, Figma exports, annotations, etc.), redact secrets, and ensure complete coverage across pages, viewports, and states. Produce fresh captures for comparison and run image diff via node "$SKILL_DIR/scripts/visual-qa.mjs" image-diff <reference.png> <actual.png> with fields like dimensionsMatch, diffRatio, similarityScore, alphaChannelIntact, hotspots[].
• For web: capture reference image, then actual screenshot (preferred via browser:control-in-app-browser when available, otherwise via Playwright/agent-browser/dev-browser tooling). Use agent-browser as a fallback with setup instructions in $SKILL_DIR/references/agent-browser-setup.md.
• For TUI: render via a real pty in a browser using xterm.js, producing terminal.png, terminal.txt, terminal-ansi.txt, and metadata.json, then run node "$SKILL_DIR/scripts/visual-qa.mjs" tui-check .omo/evidence/<slug>/tui-web-terminal/terminal.txt --cols <N> to validate width and layout.
• Step 3 - Dispatch two read-only QA subagents in parallel: run two oracle reviews concurrently via the harness. Each returns PASS, REVISE, or FAIL with concrete findings, and must include [product] or [evidence] tags in their observations. Pass A (design-system and functional integrity) and Pass B (visual fidelity and CJK precision) evaluate different aspects and use the provided evidence and CAPTURES.
• Each pass returns a structured verdict with findings and blocking items if any.

When to use it

• Use after building or changing any UI, before declaring it done.
• Use for red-flagged or important visual changes where pixel fidelity, layout accuracy, and CJK text handling matter.
• Skip when there is no rendered surface (pure backend or library logic with no visual output).

What it can touch

• It relies on the skill’s internal tooling and scripts located under the packages/shared-skills/skills/visual-qa/ directory, including the scripts/visual-qa.mjs and scripts/cli.ts components. It requires tools compatible with the described browser and terminal capture workflows, as well as the referenced agent tooling (e.g., agent-browser).

Caveats

• Uses two read-only oracle passes; results depend on the completeness and freshness of captures (must be redacted properly, and evidence must be fresh).
• The guidance enforces strict handling of reference packets and demands coverage of all enumerated pages and states; incomplete coverage is considered BLOCKING.
• The review requires handling of motion and interactions, not just static captures; animation states should be captured and compared appropriately.