---
name: run-qa
description: Start dev server and run QA testing on a feature. Handles server setup, mode selection, and QA agent spawning with correct configuration.
argument-hint: "<issue-number>"
---

# /run-qa

Start the dev server and run QA testing on a feature. Handles all the setup and spawns the QA Agent with correct configuration.

Takes an argument: issue number. E.g. `/run-qa #123`

---

## Step 1: Ensure Dev Server is Running

```bash
# Check if server is already running
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
```

**If server is not running (non-200 response):**

```bash
cd app && npm run dev
```

**If port is busy or server won't start:**

```bash
# Kill stuck processes
lsof -ti:3000 | xargs kill -9 2>/dev/null

# Try port 3001
cd app && npx next dev --port 3001
```

**60-second rule:** Never spend more than 60 seconds on server issues. Kill, restart, try another port. If it still fails after 60 seconds, report as a blocker and stop.

**Note the port** (3000, 3001, or 3002) for the QA Agent.

---

## Step 2: Choose QA Mode

| Mode | When to Use | Trigger |
|------|-------------|---------|
| **Fast QA** (Default) | All standard issues | No trigger needed |
| **Standard QA** | Complex flows, pre-release | User says "full QA" or "standard QA" |

### Fast QA (Default)

- Skip scope confirmation — start testing immediately
- Mobile-first full pass, desktop spot-check only
- Screenshots only for failures and unexpected findings
- Minimal report format (fixes required + passed list)

### Standard QA

- Scope confirmation before testing
- Full mobile pass + full desktop pass
- Full narrative TEST_REPORT.md
- Screenshots for all requirements

---

## Step 3: Read Issue Context

```bash
gh issue view <issue-number>
```

**Extract:**
- Acceptance criteria (what to test)
- Dev notes (what was built, how to test, known limitations)
- Any specific test instructions

---

## Step 4: Spawn QA Agent

The QA Agent must be configured with:

### Required Reading (Before Testing)

1. `qa/Docs/qa_contract_authoritative_rules_for_claude_code.md` — The law
2. `qa/Docs/interactive_qa_rules_claude_control_guide.md` — How to run interactive QA

### Configuration

| Setting | Value |
|---------|-------|
| **Mode** | Interactivity Mode with Playwright |
| **App URL** | `http://localhost:<port>` (from Step 1) |
| **Primary Viewport** | Mobile (390×844) |
| **Secondary Viewport** | Desktop (spot-check) |

### Evidence Requirements

| Artifact | Location | Required? |
|----------|----------|-----------|
| README.md | `qa/QA-Runs/<issue-number>/README.md` | Always |
| Screenshots | `qa/QA-Runs/<issue-number>/*.png` | Only for failures |

**README.md must include:**
- What was tested
- Pass/fail per item
- Fixes required (if any)

### QA Agent Prompt Template

```
You are the QA Agent for Block Manager.

**Read these docs first:**
- `qa/Docs/qa_contract_authoritative_rules_for_claude_code.md`
- `qa/Docs/interactive_qa_rules_claude_control_guide.md`

**Issue:** #<issue-number>
**App URL:** http://localhost:<port>
**Mode:** Fast QA / Standard QA

**Test scope:**
<acceptance-criteria-from-issue>

**Dev notes:**
<dev-notes-from-issue>

**Viewports:**
- Mobile (390×844) — full pass
- Desktop — spot-check

**Output:**
- `qa/QA-Runs/<issue-number>/README.md` with pass/fail per item
- Screenshots only if they help explain a failure
- Comment findings on GitHub issue #<issue-number>
```

---

## Step 5: Handle QA Results

### If QA Passes

```bash
# Comment on issue
gh issue comment <issue-number> -b "## QA Result: PASS

All acceptance criteria verified. See \`qa/QA-Runs/<issue-number>/README.md\` for details."
```

Proceed to `/pre-merge-check`.

### If QA Fails

```bash
# Comment on issue with findings
gh issue comment <issue-number> -b "## QA Result: FAIL

**Fixes Required:**
- <issue-1>
- <issue-2>

See \`qa/QA-Runs/<issue-number>/README.md\` for full details."

# Update labels
gh issue edit <issue-number> --add-label "needs-fixes"
```

**Next step:** Dev Agent fixes issues, then re-run `/run-qa`.

### If QA Blocked

```bash
gh issue comment <issue-number> -b "## QA Result: BLOCKED

**Blocker:** <description>

Cannot proceed until blocker is resolved."
```

---

## Automated QA → Dev Loop

For straightforward fixes, the loop can run without human intervention:

1. QA produces FAIL with "Fixes Required"
2. Read the QA report's "Fixes Required" section
3. Spawn Dev Agent with those specific fixes
4. Dev Agent fixes and pushes
5. Re-run `/run-qa`
6. Repeat until PASS (max 3 iterations)

**After 3 failures:** Stop and ask user for direction.

---

## Non-UI Issues

For issues that don't involve UI (schema changes, config, utilities):

> "This appears to be a non-UI issue. Code review is sufficient — QA testing not required. Proceed to `/pre-merge-check`?"

Skip QA only if confirmed as non-UI work.

---

## Troubleshooting

### Server Won't Start

```bash
# Check what's using the port
lsof -i:3000

# Kill all node processes if stuck
pkill -f "next dev"

# Try a different port
cd app && npx next dev --port 3002
```

### Playwright Connection Issues

```bash
# Verify server is responding
curl http://localhost:<port>

# Check for CORS or auth issues in browser console
```

### Test Credentials

Credentials are read from environment variables (`.env.local`), never hardcoded.

```bash
# Verify env file exists
cat app/.env.local | grep -E "^(TEST_|SUPABASE_)"
```