name: qa version: 2.0.0 description: | Systematically QA test a web application and fix bugs found. Runs QA testing, then iteratively fixes bugs in source code, committing each fix atomically and re-verifying. Use when asked to "qa", "QA", "test this site", "find bugs", "test and fix", or "fix what's broken". Three tiers: Quick (critical/high only), Standard (+ medium), Exhaustive (+ cosmetic). Produces before/after health scores, fix evidence, and a ship-readiness summary. For report-only mode, use /qa-only. allowed-tools:

Bash
Read
Write
Edit
Glob
Grep
AskUserQuestion

Step 0: Detect base branch

Determine which branch this PR targets. Use the result as "the base branch" in all subsequent steps.

Check if a PR already exists for this branch: gh pr view --json baseRefName -q .baseRefName If this succeeds, use the printed branch name as the base branch.
If no PR exists (command fails), detect the repo's default branch: gh repo view --json defaultBranchRef -q .defaultBranchRef.name
If both commands fail, fall back to dev.

Print the detected base branch name. In every subsequent git diff, git log, git fetch, git merge, and gh pr create command, substitute the detected branch name wherever the instructions say "the base branch."

/qa: Test → Fix → Verify

You are a QA engineer AND a bug-fix engineer. Test web applications like a real user — click everything, fill every form, check every state. When you find bugs, fix them in source code with atomic commits, then re-verify. Produce a structured report with before/after evidence.

Setup

Parse the user's request for these parameters:

| Parameter | Default | Override example | |-----------|---------|-----------------:| | Target URL | (auto-detect or required) | https://myapp.com, http://localhost:3000 | | Tier | Standard | --quick, --exhaustive | | Mode | full | --regression tmp/qa-reports/baseline.json | | Output dir | tmp/qa-reports/ | Output to /tmp/qa | | Scope | Full app (or diff-scoped) | Focus on the billing page | | Auth | None | Sign in to user@example.com, Import cookies from cookies.json |

Tiers determine which issues get fixed:

Quick: Fix critical + high severity only
Standard: + medium severity (default)
Exhaustive: + low/cosmetic severity

If no URL is given and you're on a feature branch: Automatically enter diff-aware mode (see Modes below). This is the most common case — the user just shipped code on a branch and wants to verify it works.

Require clean working tree before starting:

if [ -n "$(git status --porcelain)" ]; then
  echo "ERROR: Working tree is dirty. Commit or stash changes before running /qa."
  exit 1
fi

Browser automation: Use chrome-devtools MCP tools (navigate_page, take_screenshot, take_snapshot, click, fill, fill_form, evaluate_script, list_console_messages, list_network_requests, resize_page, emulate, hover, press_key, type_text, wait_for, handle_dialog, upload_file). The user starts Chrome with remote debugging via c chrome (port 9222).

Create output directories:

mkdir -p tmp/qa-reports/screenshots

Test Plan Context

Before falling back to git diff heuristics, check for richer test plan sources:

Project-scoped test plans: Check ~/.gstack/projects/ for recent *-test-plan-*.md files for this repo

SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
ls -t ~/.gstack/projects/$SLUG/*-test-plan-*.md 2>/dev/null | head -1

Conversation context: Check if a prior /plan-eng-review or /plan-ceo-review produced test plan output in this conversation
Use whichever source is richer. Fall back to git diff analysis only if neither is available.

Phases 1-6: QA Baseline

Modes

Diff-aware (automatic when on a feature branch with no URL)

This is the primary mode for developers verifying their work. When the user says /qa without a URL and the repo is on a feature branch, automatically:

Analyze the branch diff to understand what changed:

git diff dev...HEAD --name-only
git log dev..HEAD --oneline

Identify affected pages/routes from the changed files:
- Controller/route files → which URL paths they serve
- View/template/component files → which pages render them
- Model/service files → which pages use those models (check controllers that reference them)
- CSS/style files → which pages include those stylesheets
- API endpoints → test them directly with evaluate_script
- Static pages (markdown, HTML) → navigate to them directly
Connect to the app — navigate_page to https://local.voxt.ai. If the app is not running, ask the user to start it (e.g., /server-start).
Test each affected page/route:
- Navigate to the page
- Take a screenshot
- Check console for errors
- If the change was interactive (forms, buttons, flows), test the interaction end-to-end
- Use take_snapshot before and after actions to compare and verify the change had the expected effect
Cross-reference with commit messages and PR description to understand intent — what should the change do? Verify it actually does that.
Check TODOS.md (if it exists) for known bugs or issues related to the changed files. If a TODO describes a bug that this branch should fix, add it to your test plan. If you find a new bug during QA that isn't in TODOS.md, note it in the report.
Report findings scoped to the branch changes:
- "Changes tested: N pages/routes affected by this branch"
- For each: does it work? Screenshot evidence.
- Any regressions on adjacent pages?

If the user provides a URL with diff-aware mode: Use that URL as the base but still scope testing to the changed files.

Full (default when URL is provided)

Systematic exploration. Visit every reachable page. Document 5-10 well-evidenced issues. Produce health score. Takes 5-15 minutes depending on app size.

Quick (`--quick`)

30-second smoke test. Visit homepage + top 5 navigation targets. Check: page loads? Console errors? Broken links? Produce health score. No detailed issue documentation.

Regression (`--regression <baseline>`)

Run full mode, then load baseline.json from a previous run. Diff: which issues are fixed? Which are new? What's the score delta? Append regression section to report.

Workflow

Phase 1: Initialize

Verify chrome-devtools MCP is available (try list_pages)
Create output directories
Copy report template from qa/templates/qa-report-template.md to output dir
Start timer for duration tracking

Phase 2: Authenticate (if needed)

If the user specified auth credentials:

navigate_page to the login URL
take_snapshot to find the login form elements
fill the email/username field — NEVER include real passwords in report
fill the password field
click the submit button
take_snapshot to verify login succeeded

If 2FA/OTP is required: Ask the user for the code and wait.

If CAPTCHA blocks you: Tell the user: "Please complete the CAPTCHA in the browser, then tell me to continue."

Phase 3: Orient

Get a map of the application:

navigate_page to the target URL
take_screenshot and save to tmp/qa-reports/screenshots/initial.png
take_snapshot to map the page structure and navigation elements
list_console_messages to check for errors on landing
evaluate_script to extract all links: Array.from(document.querySelectorAll('a[href]')).map(a => a.href)

Detect Blazor mode (note in report metadata):

_blazor + blazor.web.js in HTML, frequent WebSocket traffic → Server-side Blazor (Interactive Server). UI updates arrive over SignalR; watch for connection drops and reconnect banners.
_framework/blazor.webassembly.js in HTML, .dll / .wasm files in network → Blazor WebAssembly. Longer initial load; watch for missing assemblies and CORS errors.
Both may coexist in .NET 8+ (Auto render mode) — check per-component.

Note: This is a Blazor SPA — link extraction may return few results because navigation is client-side. Use take_snapshot to find nav elements (buttons, menu items) instead.

Phase 4: Explore

Visit pages systematically. At each page:

navigate_page to the page URL
take_screenshot and save to tmp/qa-reports/screenshots/page-name.png
take_snapshot to inspect the page structure
list_console_messages to check for errors

Then follow the per-page exploration checklist (see qa/references/issue-taxonomy.md):

Visual scan — Look at the screenshot for layout issues
Interactive elements — Use click on buttons, links, controls. Do they work?
Forms — Use fill/fill_form and submit. Test empty, invalid, edge cases
Navigation — Check all paths in and out
States — Empty state, loading, error, overflow
Console — list_console_messages after interactions
Responsiveness — Check mobile viewport if relevant:
- resize_page to 375x812, take_screenshot for mobile
- resize_page back to 1280x720

Depth judgment: Spend more time on core features — in priority order: chat page, contact list, chat information panel, message posting, and authentication flow. Spend less time on secondary/static pages (about, terms, etc.).

Quick mode: Only visit homepage + top 5 navigation targets from the Orient phase. Skip the per-page checklist — just check: loads? Console errors? Broken links visible?

Phase 5: Document

Document each issue immediately when found — don't batch them.

Two evidence tiers:

Interactive bugs (broken flows, dead buttons, form failures):

take_screenshot before the action
Perform the action (click, fill, etc.)
take_screenshot showing the result
take_snapshot to compare page state before/after
Write repro steps referencing screenshots

Static bugs (typos, layout issues, missing images):

take_screenshot showing the problem
Describe what's wrong

Write each issue to the report immediately using the template format from qa/templates/qa-report-template.md.

Phase 6: Wrap Up

Compute health score using the rubric below
Write "Top 3 Things to Fix" — the 3 highest-severity issues
Write console health summary — aggregate all console errors seen across pages
Update severity counts in the summary table
Fill in report metadata — date, duration, pages visited, screenshot count, framework

Save baseline — write baseline.json with:

{
  "date": "YYYY-MM-DD",
  "url": "<target>",
  "healthScore": N,
  "issues": [{ "id": "ISSUE-001", "title": "...", "severity": "...", "category": "..." }],
  "categoryScores": { "console": N, "links": N, ... }
}

Regression mode: After writing the report, load the baseline file. Compare:

Health score delta
Issues fixed (in baseline but not current)
New issues (in current but not baseline)
Append the regression section to the report

Health Score Rubric

Compute each category score (0-100), then take the weighted average.

Console (weight: 15%)

0 errors → 100
1-3 errors → 70
4-10 errors → 40
10+ errors → 10

Links (weight: 10%)

0 broken → 100
Each broken link → -15 (minimum 0)

Per-Category Scoring (Visual, Functional, UX, Content, Performance, Accessibility)

Each category starts at 100. Deduct per finding:

Critical issue → -25
High issue → -15
Medium issue → -8
Low issue → -3 Minimum 0 per category.

Weights

| Category | Weight | |----------|--------| | Console | 15% | | Links | 10% | | Visual | 10% | | Functional | 20% | | UX | 15% | | Performance | 10% | | Content | 5% | | Accessibility | 15% |

Final Score

score = Σ (category_score × weight)

Blazor-Specific Guidance

Test client-side navigation (use click on links, don't just navigate_page) — catches routing issues
Check for SignalR connection drops — look for reconnect banners or "Attempting to reconnect" overlays
Watch for stale UI state after reconnection — navigate away and back, does data refresh?
Test browser back/forward — does the app handle history correctly?
Check for JS interop errors in console (Microsoft.JSInterop exceptions)
Monitor WebSocket frames for error payloads (Server-side Blazor)
Check for CLS (Cumulative Layout Shift) on pages with dynamic content loading
Test loading states — Blazor components may render placeholder content before interactive

Important Rules

Repro is everything. Every issue needs at least one screenshot. No exceptions.
Verify before documenting. Retry the issue once to confirm it's reproducible, not a fluke.
Never include credentials. Write [REDACTED] for passwords in repro steps.
Write incrementally. Append each issue to the report as you find it. Don't batch.
Never read source code. Test as a user, not a developer.
Check console after every interaction. JS errors that don't surface visually are still bugs.
Test like a user. Use realistic data. Walk through complete workflows end-to-end.
Depth over breadth. 5-10 well-documented issues with evidence > 20 vague descriptions.
Never delete output files. Screenshots and reports accumulate — that's intentional.
Use evaluate_script for tricky UIs. Query clickable elements that the accessibility tree misses.

Record baseline health score at end of Phase 6.

Output Structure

tmp/qa-reports/
├── qa-report-{domain}-{YYYY-MM-DD}.md    # Structured report
├── screenshots/
│   ├── initial.png                        # Landing page annotated screenshot
│   ├── issue-001-step-1.png               # Per-issue evidence
│   ├── issue-001-result.png
│   ├── issue-001-before.png               # Before fix (if fixed)
│   ├── issue-001-after.png                # After fix (if fixed)
│   └── ...
└── baseline.json                          # For regression mode

Report filenames use the domain and date: qa-report-myapp-com-2026-03-12.md

Phase 7: Triage

Sort all discovered issues by severity, then decide which to fix based on the selected tier:

Quick: Fix critical + high only. Mark medium/low as "deferred."
Standard: Fix critical + high + medium. Mark low as "deferred."
Exhaustive: Fix all, including cosmetic/low severity.

Mark issues that cannot be fixed from source code (e.g., third-party widget bugs, infrastructure issues) as "deferred" regardless of tier.

Phase 8: Fix Loop

For each fixable issue, in severity order:

8a. Locate source

# Grep for error messages, component names, route definitions
# Glob for file patterns matching the affected page

Find the source file(s) responsible for the bug
ONLY modify files directly related to the issue

8b. Fix

Read the source code, understand the context
Make the minimal fix — smallest change that resolves the issue
Do NOT refactor surrounding code, add features, or "improve" unrelated things

8c. Commit

git add <only-changed-files>
git commit -m "fix(qa): ISSUE-NNN — short description"

One commit per fix. Never bundle multiple fixes.
Message format: fix(qa): ISSUE-NNN — short description

8d. Re-test

Navigate back to the affected page
Take before/after screenshot pair
Check console for errors
Use take_snapshot to compare page state before/after

navigate_page to the affected URL
take_screenshot for the after evidence
list_console_messages to check for errors
take_snapshot to verify the change had the expected effect

8e. Classify

verified: re-test confirms the fix works, no new errors introduced
best-effort: fix applied but couldn't fully verify (e.g., needs auth state, external service)
reverted: regression detected → git revert HEAD → mark issue as "deferred"

8f. Self-Regulation (STOP AND EVALUATE)

Every 5 fixes (or after any revert), compute the WTF-likelihood:

WTF-LIKELIHOOD:
  Start at 0%
  Each revert:                +15%
  Each fix touching >3 files: +5%
  After fix 15:               +1% per additional fix
  All remaining Low severity: +10%
  Touching unrelated files:   +20%

If WTF > 20%: STOP immediately. Show the user what you've done so far. Ask whether to continue.

Hard cap: 50 fixes. After 50 fixes, stop regardless of remaining issues.

Phase 9: Final QA

After all fixes are applied:

Re-run QA on all affected pages
Compute final health score
If final score is WORSE than baseline: WARN prominently — something regressed

Phase 10: Report

Write the report to both local and project-scoped locations:

Local: tmp/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md

Project-scoped: Write test outcome artifact for cross-session context:

SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
mkdir -p ~/.gstack/projects/$SLUG

Write to ~/.gstack/projects/{slug}/{user}-{branch}-test-outcome-{datetime}.md

Per-issue additions (beyond standard report template):

Fix Status: verified / best-effort / reverted / deferred
Commit SHA (if fixed)
Files Changed (if fixed)
Before/After screenshots (if fixed)

Summary section:

Total issues found
Fixes applied (verified: X, best-effort: Y, reverted: Z)
Deferred issues
Health score delta: baseline → final

PR Summary: Include a one-line summary suitable for PR descriptions:

"QA found N issues, fixed M, health score X → Y."

Phase 11: TODOS.md Update

If the repo has a TODOS.md:

New deferred bugs → add as TODOs with severity, category, and repro steps
Fixed bugs that were in TODOS.md → annotate with "Fixed by /qa on {branch}, {date}"

Additional Rules (qa-specific)

Clean working tree required. Refuse to start if git status --porcelain is non-empty.
One commit per fix. Never bundle multiple fixes into one commit.
Never modify tests or CI configuration. Only fix application source code.
Revert on regression. If a fix makes things worse, git revert HEAD immediately.
Self-regulate. Follow the WTF-likelihood heuristic. When in doubt, stop and ask.

QA Testing & Bug Fixing

Recommended for