# QA Workflow Phases


## Contents

- [Phase 1: Initialize](#phase-1-initialize)
- [Phase 2: Authenticate (if needed)](#phase-2-authenticate-if-needed)
- [Phase 3: Orient](#phase-3-orient)
- [Phase 4: Explore](#phase-4-explore)
- [Phase 5: Document](#phase-5-document)
- [Phase 6: Wrap Up](#phase-6-wrap-up)
- [Phase 7: Triage](#phase-7-triage)
- [Phase 8: Fix Loop](#phase-8-fix-loop)
  - [8a. Locate source](#8a-locate-source)
  - [8b. Fix](#8b-fix)
  - [8c. Commit](#8c-commit)
  - [8d. Re-test](#8d-re-test)
  - [8e. Classify](#8e-classify)
  - [8e.5. Regression Test](#8e5-regression-test)
  - [8f. Self-Regulation (STOP AND EVALUATE)](#8f-self-regulation-stop-and-evaluate)
- [Phase 9: Final QA](#phase-9-final-qa)
- [Phase 10: Report](#phase-10-report)
- [Phase 11: TODOS.md Update](#phase-11-todosmd-update)

## Phase 1: Initialize

1. Find browse binary (see `references/setup.md`)
2. Create output directories
3. Copy report template from `qa/templates/qa-report-template.md` to output dir
4. Start timer for duration tracking

## Phase 2: Authenticate (if needed)

**If the user specified auth credentials:**

```bash
agent-browser open <login-url>
agent-browser snapshot -i                  # find the login form
agent-browser fill @e3 "user@example.com"
agent-browser fill @e4 "[REDACTED]"        # NEVER include real passwords in report
agent-browser click @e5                    # submit
agent-browser snapshot -i                  # verify login succeeded
```

**If the user provided a saved auth state:**

```bash
agent-browser open <target-url> --state ./auth-state.json
```

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

```bash
agent-browser open <target-url>
agent-browser snapshot -i
agent-browser screenshot --annotate "$REPORT_DIR/screenshots/initial.png"
agent-browser eval "JSON.stringify(Array.from(document.links).map(l=>({href:l.href,text:l.innerText.trim()})))"  # map navigation
agent-browser console --errors                                                                                    # any errors on landing?
```

**Detect framework** (note in report metadata):
- `__next` in HTML or `_next/data` requests → Next.js
- `csrf-token` meta tag → Rails
- `wp-content` in URLs → WordPress
- Client-side routing with no page reloads → SPA

**For SPAs:** The links eval may return few results because navigation is client-side. Use `snapshot -i` to find nav elements (buttons, menu items) instead.

## Phase 4: Explore

Visit pages systematically. At each page:

```bash
agent-browser open <page-url>
agent-browser snapshot -i
agent-browser screenshot --annotate "$REPORT_DIR/screenshots/page-name.png"
agent-browser console --errors
```

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

1. **Visual scan** — Look at the annotated 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
6. **Console** — Any new JS errors after interactions?
7. **Responsiveness** — Check mobile viewport if relevant:
   ```bash
   agent-browser set viewport 375 812
   agent-browser screenshot "$REPORT_DIR/screenshots/page-mobile.png"
   agent-browser set viewport 1280 720
   ```

**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 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):
1. Take a screenshot before the action
2. Perform the action
3. Take a screenshot showing the result
4. Capture the post-action snapshot to show new state
5. Write repro steps referencing screenshots

```bash
agent-browser screenshot "$REPORT_DIR/screenshots/issue-001-step-1.png"
agent-browser click @e5
agent-browser screenshot "$REPORT_DIR/screenshots/issue-001-result.png"
agent-browser snapshot -i
```

**Static bugs** (typos, layout issues, missing images):
1. Take a single annotated screenshot showing the problem
2. Describe what's wrong

```bash
agent-browser snapshot -i
agent-browser screenshot --annotate "$REPORT_DIR/screenshots/issue-002.png"
```

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

## Phase 6: Wrap Up

1. **Compute health score** using the rubric in `references/health-score.md`
2. **Write "Top 3 Things to Fix"** — the 3 highest-severity issues
3. **Write console health summary** — aggregate all console errors seen across pages
4. **Update severity counts** in the summary table
5. **Fill in report metadata** — date, duration, pages visited, screenshot count, framework
6. **Save baseline** — write `baseline.json` with:
   ```json
   {
     "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

Record baseline health score at end of Phase 6.

---

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

```bash
# 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

```bash
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
- Capture a fresh snapshot to verify the change had the expected effect

```bash
agent-browser open <affected-url>
agent-browser screenshot "$REPORT_DIR/screenshots/issue-NNN-after.png"
agent-browser console --errors
agent-browser snapshot -i
```

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

### 8e.5. Regression Test

Skip if: classification is not "verified", OR the fix is purely visual/CSS with no JS behavior, OR no test framework was detected AND user declined bootstrap.

**1. Study the project's existing test patterns:**

Read 2-3 test files closest to the fix (same directory, same code type). Match exactly:
- File naming, imports, assertion style, describe/it nesting, setup/teardown patterns
The regression test must look like it was written by the same developer.

**2. Trace the bug's codepath, then write a regression test:**

Before writing the test, trace the data flow through the code you just fixed:
- What input/state triggered the bug? (the exact precondition)
- What codepath did it follow? (which branches, which function calls)
- Where did it break? (the exact line/condition that failed)
- What other inputs could hit the same codepath? (edge cases around the fix)

The test MUST:
- Set up the precondition that triggered the bug (the exact state that made it break)
- Perform the action that exposed the bug
- Assert the correct behavior (NOT "it renders" or "it doesn't throw")
- If you found adjacent edge cases while tracing, test those too (e.g., null input, empty array, boundary value)
- Include full attribution comment:
  ```
  // Regression: ISSUE-NNN — {what broke}
  // Found by /mk:qa on {YYYY-MM-DD}
  // Report: .claude/memory/qa-reports/qa-report-{domain}-{date}.md
  ```

Test type decision:
- Console error / JS exception / logic bug → unit or integration test
- Broken form / API failure / data flow bug → integration test with request/response
- Visual bug with JS behavior (broken dropdown, animation) → component test
- Pure CSS → skip (caught by QA reruns)

Generate unit tests. Mock all external dependencies (DB, API, Redis, file system).

Use auto-incrementing names to avoid collisions: check existing `{name}.regression-*.test.{ext}` files, take max number + 1.

**3. Run only the new test file:**

```bash
{detected test command} {new-test-file}
```

**4. Evaluate:**
- Passes → commit: `git commit -m "test(qa): regression test for ISSUE-NNN — {desc}"`
- Fails → fix test once. Still failing → delete test, defer.
- Taking >2 min exploration → skip and defer.

**5. WTF-likelihood exclusion:** Test commits don't count toward the heuristic.

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

1. Re-run QA on all affected pages
2. Compute final health score
3. **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:** `.claude/memory/qa-reports/qa-report-{domain}-{YYYY-MM-DD}.md`

**Project-scoped:** Write test outcome artifact for cross-session context:
```bash
eval "$(.claude/scripts/bin/workflow-slug 2>/dev/null)" && mkdir -p .claude/memory/projects
```
Write to `.claude/memory/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`:

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