Visual QA Checkpoint Skill

Visual QA Checkpoint

Lightweight visual smoke test for UI-facing changes.

Writes result to .checkpoints/visual-qa.json.

IMPORTANT: Not for Workers on Worktrees

This checkpoint should only be run by the conductor AFTER merging changes to main.

Workers on git worktrees cannot run visual-qa because:

Changes aren't built - The extension/app isn't rebuilt with worktree changes
No isolated browser - Workers share the same Chrome instance
Tab group conflicts - Multiple workers fighting for tabs (especially if groups disabled)
Dev server conflicts - Multiple npm run dev instances on same port

Correct workflow:

Worker completes code changes and commits
Conductor merges to main
Conductor rebuilds extension/app
Conductor runs /conductor:visual-qa on main branch

Heuristics (v1)

If no UI-facing files changed (no changes under extension/ and no *.css, *.tsx, *.jsx) → PASS (skipped).
Otherwise → perform a quick smoke test and record PASS/FAIL.

Workflow

Step 1: Detect UI-facing Changes

CHANGED=$( (git diff --name-only main...HEAD 2>/dev/null || true) ; git diff --name-only 2>/dev/null || true ; git diff --cached --name-only 2>/dev/null || true )
CHANGED=$(echo "$CHANGED" | sed '/^$/d' | sort -u)

if echo "$CHANGED" | grep -qE '^(extension/)|(\.tsx$)|(\.jsx$)|(\.css$)'; then
  NEEDS_VISUAL=1
else
  NEEDS_VISUAL=0
fi

Step 2: Tab Group Isolation (MANDATORY)

BEFORE any browser work, create YOUR OWN tab group with a random 3-digit suffix.

This is mandatory because:

User can switch tabs at any time - active tab is unreliable
Multiple Claude workers may run simultaneously
Your operations target YOUR tabs, not the user's browsing

# 1. Generate random ID
SESSION_ID="Claude-$(shuf -i 100-999 -n 1)"

# 2. Create group
mcp-cli call tabz/tabz_create_group '{"title": "'$SESSION_ID'", "color": "cyan"}'
# Returns: {"groupId": 123, ...}

# 3. Open URLs into YOUR group (use returned groupId)
mcp-cli call tabz/tabz_open_url '{"url": "https://example.com", "groupId": 123}'

# 4. Always use explicit tabId from your group - NEVER rely on active tab

Step 3: Run Smoke Test (if needed)

If NEEDS_VISUAL=1, do the quickest relevant check:

Open the extension side panel and ensure it loads
Trigger the affected UI path
Check browser console for errors
Take a screenshot for evidence

If you have Tabz MCP available, you can use it (preferred):

tabz_get_console_logs (errors)
tabz_screenshot (capture)
tabz_enable_network_capture + tabz_get_network_requests (API failures)

Always pass explicit tabId - never rely on "active tab":

# Get your tab's ID from your group
mcp-cli call tabz/tabz_screenshot '{"tabId": YOUR_TAB_ID}'
mcp-cli call tabz/tabz_get_console_logs '{"tabId": YOUR_TAB_ID}'

If Tabz MCP isn't available, do a manual check and note it.

Step 4: Write Checkpoint File

mkdir -p .checkpoints
cat > .checkpoints/visual-qa.json << EOF
{
  "checkpoint": "visual-qa",
  "timestamp": "$(date -Iseconds)",
  "passed": ${PASSED},
  "needs_visual": ${NEEDS_VISUAL},
  "summary": "${SUMMARY}"
}
EOF

Agent Skills: Visual QA Checkpoint

Install this agent skill to your local

Skill Files