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:

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

Correct workflow:

1. Worker completes code changes and commits
2. Conductor merges to main
3. Conductor rebuilds extension/app
4. 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