qa

What this skill does

# 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.

**Browser requirement:** This skill requires a headless browser (Playwright MCP or similar). If no browser tool is available, inform the user.

## 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` |
| Scope | Full app (or diff-scoped) | `Focus on the billing page` |

**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).

**Check for clean working tree:**

```bash
bash "$CLAUDE_PLUGIN_ROOT/scripts/clean-tree-check.sh"
```

If it exits non-zero (working tree is dirty — output shows the offending files), **STOP** and use AskUserQuestion:

"Your working tree has uncommitted changes. /qa needs a clean tree so each bug fix gets its own atomic commit."

- A) Commit my changes — commit all current changes with a descriptive message, then start QA
- B) Stash my changes — stash, run QA, pop the stash after
- C) Abort — I'll clean up manually

After the user chooses, execute their choice (commit or stash), then continue with setup.

---

## 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:

1. **Analyze the branch diff** to understand what changed:
   ```bash
   git diff main...HEAD --name-only
   git log main..HEAD --oneline
   ```

2. **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
   - CSS/style files → which pages include those stylesheets
   - API endpoints → test them directly
   - Static pages → navigate to them directly
   - Migration/schema files → identify which models are affected, then trace to pages that display or mutate that data. If migrations exist in the diff, verify the app still loads correctly (schema changes can break everything).
   - Seeder/fixture files → check if test data looks correct on relevant pages

   **If no obvious pages/routes are identified:** Fall back to Quick mode — navigate to the homepage, follow the top 5 navigation targets, check console for errors, and test any interactive elements found.

3. **Detect the running app** — check common local dev ports (3000, 4000, 8080). If no local app is found, ask the user for the URL.

4. **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

5. **Cross-reference with commit messages** to understand *intent* — what should the change do? Verify it actually does that.

6. **Check TODOS.md** (if it exists) for known bugs related 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.

### Quick (`--quick`)
30-second smoke test. Visit homepage + top 5 navigation targets. Check: page loads? Console errors? Broken links? Produce health score.

### Regression (`--regression`)
Run full mode, then compare against a previous baseline. Diff: which issues are fixed? Which are new? What's the score delta?

---

## Workflow

### Phase 1: Initialize

1. Ensure browser is available
2. Create output directories for screenshots and report
3. Start timer for duration tracking

### Phase 2: Authenticate (if needed)

If the user specified auth credentials, navigate to the login page and authenticate. **NEVER include real passwords in the report** — write `[REDACTED]`.

If CAPTCHA blocks you, tell the user to complete it manually.

### Phase 3: Orient

Get a map of the application:

1. Navigate to the target URL
2. Take an annotated screenshot
3. Map navigation structure (links, menus)
4. Check console for errors on landing

**Detect framework** (note in report metadata): Next.js, Rails, WordPress, SPA, etc.

### Phase 4: Explore

Visit pages systematically. At each page:

1. **Visual scan** — Look at the screenshot for layout issues
2. **Interactive elements** — Click buttons, links, controls. Do they work?
3. **Forms** — Fill and submit. Test empty, invalid, edge cases
4. **Navigation** — Check all paths in and out
5. **States** — Empty state, loading, error, overflow. For loading states: if the page loads instantly, throttle the network to 3G or add artificial latency to observe skeleton screens, spinners, and progress indicators — don't just hope to catch them on a fast connection.
6. **Console & Network** — Check for JS errors after interactions. Also monitor network requests: look for failed API calls (4xx/5xx responses), CORS errors, and unusually slow responses (>2s). A silent 500 from an API endpoint is just as much a bug as a visible JS error.
7. **Responsiveness** — Check mobile viewport if relevant
8. **Accessibility** — Tab through every interactive element on the page. Verify: focus indicators are visible, tab order is logical, no keyboard traps exist. Check that images have meaningful alt text, form inputs have associated labels, and ARIA attributes are used correctly (not just present but semantically accurate). Test with color contrast in mind — text should meet WCAG AA (4.5:1 for normal text, 3:1 for large text). If the page has modals or dropdowns, confirm they can be opened, navigated, and dismissed with keyboard alone.
9. **Security surface check** — Quick scan for obvious issues: are form actions pointing where expected? Are there open redirect parameters in URLs (`?redirect=`, `?next=`, `?return_to=`)? Is sensitive data (tokens, emails, internal IDs) visible in page source or URL parameters? Check that the page is served over HTTPS and isn't loading mixed content. This isn't a pentest — just catch the low-hanging fruit a user might stumble into.

**Depth judgment:** Spend more time on core features (homepage, dashboard, checkout, search) and less on secondary pages (about, terms, privacy).

**Quick mode:** Only visit homepage + top 5 navigation targets. 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.

**Evidence required:**
- Interactive bugs: before/after screenshot pair + repro steps
- Static bugs: single annotated screenshot + description

### Phase 6: Wrap Up

1. **Compute health score** using the rubric below
2. **Write "Top 3 Things to Fix"** — the 3 highest-severity issues
3. **Write console health summary** — aggregate all console errors across pages
4. **Update severity counts** in the summary table

---

## Health Score Rubric

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

### Console (weight: 10%)
- 0 errors → 100
- 1-3 errors → 70
- 4-10 errors → 40
- 11-20 errors → 20
- 21-50 errors → 10
- 50+ errors → 0

### Network (weight: 5%)
- 0 failed requests → 100
- 1-2 failed requests → 60
- 3-5 failed requests → 30
- 6+ failed requests → 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