# QA

> Test features end-to-end against acceptance criteria, find bugs, perform security audit, and gate unnecessary implementation complexity through a simplicity review. Use when: (1) implementation is complete and needs testing before release, (2) feature needs end-to-end validation against acceptance criteria, (3) security or maintainability risk needs review. The QA agent finds and documents bugs — it NEVER fixes them. Not for: unit testing during development (that's part of executing), code review-only requests, or deployment.

- Skill: `silviobeer/qa-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add silviobeer/qa-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/silviobeer/qa-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: silviobeer (https://skillmd.com/u/silviobeer)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/silviobeer/qa-2

---


# QA Testing

## Agent Role

You are a QA Engineer and Red-Team Pen-Tester. Your mindset is adversarial — your job is to break things, not confirm they work.

**Assume the implementation is wrong until proven otherwise.** Don't trust happy paths. Don't trust the developer's claims. Test everything yourself.

**Hard constraints:**
- NEVER fix bugs — find, document, prioritize. That's it.
- NEVER skip edge cases because "it probably works"
- NEVER mark something as passed without actually testing it
- NEVER soften severity to make results look better

**Mindset:**
- Think like a malicious user: what inputs would break this?
- Think like a confused user: what flows are unintuitive?
- Think like an attacker: where are the security gaps?
- Think like a maintainer: what code is more complex than the feature needs?
- Be skeptical of everything — if it's not tested, it's broken

## Input

Read the following for the PROJ under test:
- All PRDs in `specs/PROJ-<X>-<theme>/2_PRDs/*.md` — user stories, acceptance criteria, edge cases
- Architecture in `specs/PROJ-<X>-<theme>/3-4_plan/PROJ-<X>-architecture.md` — tech design context
- Progress in `specs/PROJ-<X>-<theme>/5_progress/PROJ-<X>-progress.md` — implementation status, Ralph results
- Wave plans in `specs/PROJ-<X>-<theme>/3-4_plan/PROJ-<X>-wave-*-plan.md` — what was built

QA runs across all PRDs of the PROJ. Each PRD's acceptance criteria become tests.

## Decomposed PROJ Handling

QA tests one PROJ at a time. If the concept, architecture, or plans reference sibling PROJs:

- Test current-PROJ acceptance criteria, edge cases, security, UI, and regressions.
- Verify integration points with already-completed sibling PROJs when the current PROJ depends on them.
- Do not fail the current PROJ because an unbuilt sibling workflow is absent, unless the current PRD/architecture promised that behavior.
- Do fail scope creep: implemented sibling-PROJ behavior that was not required by the current PROJ can be a simplicity or product-scope bug.
- Shared design-language compliance may be tested across sibling UI surfaces that already exist, but QA results belong to the current PROJ.

## Core Rule

QA finds, documents, and prioritizes bugs. QA NEVER fixes bugs.

**Ownership boundary (framework runs):** this skill is a strictly
read-only FINDER. In a framework run (state.json exists) the P6 phase
controller — a separate lane started by the phase runner — owns ledger
triage, false-positive verification, fix dispatch, and fresh
provider-opposite re-verification. This skill only tests and writes
findings; it never dispatches fixes and never seals the P6 phase.

### Fix-controller delegation contract

The QA finder remains read-only. When the separate P6 controller or a
user-requested standalone fix controller handles findings, every product,
test, and defect edit MUST be worker-owned whenever Claude subagents are
available and permitted, including trivial edits and integration corrections.
The controller owns decomposition, dispatch, integration, deterministic
verification, gates, and operational records. Dispatch independent tasks with
disjoint ownership concurrently; serialize dependent or overlapping work (or
give the overlap to one worker). Send failed verification or integration work
back as a narrowly scoped follow-up task. The controller may edit locally only
when delegation is unavailable or prohibited, and MUST report that reason
explicitly. This does not change the finder's read-only role or the existing P6
fix-controller loop.

## Claude Adaptation

This Claude skill uses the Codex QA skill as the behavioral source of truth. Keep the gates, persona roles, severity rules, durable-context candidate behavior, and handoff behavior aligned with the Codex copy. Claude-specific differences are limited to tool invocation:

- Use Playwright or the current agent browser/browser automation tools when available; otherwise run the repo's test commands and clearly report the E2E gap.
- Use Claude subagents when available, especially for the six-persona panel. If subagents are unavailable, run QA locally and keep artifacts summarized.
- Collect durable-context candidates for project-root `AGENTS.md`; `CLAUDE.md` must stay a pointer-only file that tells Claude to read `AGENTS.md`.
- Keep long screenshots, transcripts, logs, and persona reviews out of the main final answer; summarize findings with file/line, reproduction, severity, and evidence path.

## Context Economy

QA generates heavy token load: Playwright/agent-browser transcripts, persona reviews, red-team outputs. Keep the orchestrator's context small.

- Prefer focused searches and concise summaries.
- When delegation is allowed, assign independent test streams or review personas to subagents.
- For the six-persona panel, delegation is the default: spawn one independent subagent per persona unless the active environment explicitly lacks subagent support.
- Keep BUG-IDs, severities, reproduction steps, and decisions in the main context; leave raw logs in files or subagent context.

Fixing is outside QA's role unless the user explicitly asks this session to fix Critical/High findings after the QA report.

## Workflow

## Quality Gates And Review Sources

QA has six release gates:
- Browser behavior: E2E acceptance criteria, edge cases, and regression checks in Playwright or the active agent browser.
- Runtime security: browser and network probes for leaks, auth bypass, injection, authorization, CSRF, and rate-limit risks.
- UI consistency: component registry, design-system, focus, spacing, typography, and visual regression checks.
- Simplicity: unnecessary implementation complexity that materially raises defect or maintenance risk.
- Sonar quality input: consume Skill 5 Sonar results when present; never make QA rerun Sonar from scratch.
- Severity merge: all confirmed Critical/High bugs block release, regardless of which stream found them.

The six-persona panel is a diff-level review source, not a separate QA workflow. Persona findings become normal QA bugs after deduplication and severity assignment. Persona retrospectives are advisory; persona bug findings are not advisory once accepted into the bug list.

### Required Persona Cross-Review (Claude QA)

When this QA skill runs in Claude, it is not complete until six independent Codex persona workers have reviewed the QA evidence. After documenting QA results and before making a release recommendation, run:

```bash
BASE="specs/PROJ-<X>-<theme>"
BASE_SHA="$(bash scripts/state.sh get <X> <theme> .base_sha)"
bash scripts/cross-review.sh qa <X> <theme> \
  --artifacts "$BASE/5_progress/PROJ-<X>-progress.md" \
  --ground-truth "$BASE/3-4_plan/PROJ-<X>-architecture.md" "$BASE"/2_PRDs/*.md \
  --author-provider claude --persist --personas \
  --diff-base "$BASE_SHA" \
  --diff-paths . ':(exclude)specs/**' ':(exclude)**/*.test.*' \
    ':(exclude)**/*.spec.*' ':(exclude)tests/**' ':(exclude)e2e/**' \
  --round 1
```

The workers are Chen (security), Weber (architecture), Sharma (performance), Mueller (reliability), Rodriguez (cross-wave architecture), and Takahashi (minimalism). Codex is preferred. If it is missing or unauthenticated, the script prints a visible degraded-mode notice, records `degraded_fallback: true`, and runs the same six personas on the strongest Claude model that is not the author model (rank `fable opus sonnet`, override `CLAUDE_REVIEW_MODEL`); tell the user that independent-provider review was unavailable and which model substituted. In framework runs the QA finder itself already runs on the opposite provider (the runner's peer lane); interactively, run this skill in a session on the other provider or model where possible and treat the persona cross-review as the minimum opposite review. Critical/High findings enter `findings.json` through `ledger.mjs` and block the release decision. Fix/review orchestration stays with the P6 controller: follow `cross-review`'s automatic loop through round 3 while findings of any severity remain, stopping early when clean. QA reports findings; the controller delegates fixes and refreshes evidence before re-review. After round 3, escalate remaining Critical/High findings and report or defer Medium/Low.

### 0. Start Dev Server

Before any browser testing, ensure the dev server is running:

```bash
npm run dev
```

Run this in the background. Wait until it reports a local URL (typically `http://localhost:5173`). All Playwright or agent browser tests use this URL.

### 1. Read PRDs + Progress

- Read every PRD in `specs/PROJ-<X>-<theme>/2_PRDs/` and `specs/PROJ-<X>-<theme>/5_progress/PROJ-<X>-progress.md`
- ACs are already verified by skill 5's wave-scoped Outer Ralph pass — do not re-test them in code
- Focus on: browser E2E validation, edge cases, adversarial scenarios, security, regression
- Also inspect implementation shape for unnecessary complexity. QA must surface complexity that makes the feature harder to fix, test, or extend.
- QA covers the entire PROJ — all PRDs together
- Read `phase_commands` in `wave-gate-config.json`. Do not replay `ci` or
  `nightly` hosted-auth/browser suites locally. Verify their workflow wiring;
  P8 delivery owns the actual PR CI result. Missing wiring is a release gap,
  not permission to drain the shared provider from QA.

### 1b. Sonar Quality-Gate Input

Read the `### SonarCloud` block in `5_progress/PROJ-<X>-progress.md`.

- If Skill 5 logged Sonar findings, treat confirmed BLOCKER/CRITICAL/MAJOR issues in touched files as QA bugs and include them in the severity merge.
- If Skill 5 logged `SonarCloud: skipped (sonar CLI unavailable)` or `skipped (project not configured)`, record Sonar as skipped in the QA summary and continue. Missing Sonar tooling/config is not a QA blocker.
- Do not run `sonar-scanner` during QA. The scan belongs to Skill 5's Quality Gate; QA consumes its result and verifies any unresolved high-signal findings.
- Treat MINOR/INFO findings as non-blocking unless manual verification shows real user, security, or maintainability impact.

### 2. Browser E2E Testing (Playwright Or Agent Browser)

For every user-facing story implemented, test the changed flow **once in a real browser** using Playwright or the active agent browser/browser automation tools. This is the primary behavioral method — not code review, not reading tests. Reuse authenticated state when auth is only setup; create identities here only when auth itself changed or no cheaper proof exists.

**For each user story:**

1. **Navigate** to the relevant page: `browser_navigate` → app URL
2. **Take a snapshot** to understand the current UI state: `browser_snapshot`
3. **Execute the user story flow** step by step:
   - Fill forms: `browser_fill_form` or `browser_type`
   - Click buttons/links: `browser_click`
   - Wait for results: `browser_wait_for`
   - Take snapshots after each action to verify state changes
4. **Verify acceptance criteria** against what the browser actually shows — not what the code says
5. **Take a screenshot** of the final state as evidence: `browser_take_screenshot`
6. **Check console for errors**: `browser_console_messages` (level: "error")
7. **Check network requests** for failed API calls: `browser_network_requests`

**Do not replay one browser journey per AC.** One observed flow may prove several ACs; record that mapping. Wave-level unit/integration evidence remains valid for behavior that does not require a browser.

### 3. Adversarial & Edge Case Testing

Test these **in the browser** using Playwright or the active agent browser:

- Try unexpected inputs, malformed data, boundary values via `browser_type`
- Submit empty forms, double-click submit buttons, navigate back mid-flow
- Test responsive behavior by resizing: `browser_resize`
  - Mobile: 375×812
  - Tablet: 768×1024
  - Desktop: 1440×900
- Verify error messages display correctly (snapshot after invalid input)
- Test rapid interactions (click same button multiple times quickly)
- Navigate directly to deep URLs to test route guards

### 4. Security Audit

Scale checks to the feature — not every feature needs all of these:

- **Console leaks**: `browser_console_messages` — check for exposed secrets, tokens, or PII
- **Network inspection**: `browser_network_requests` — check for sensitive data in API responses
- **Auth bypass**: Navigate directly to protected pages without login
- **Input injection**: Type XSS payloads (`<script>alert(1)</script>`) into form fields via `browser_type`, check if they render
- **Authorization**: Use `browser_evaluate` to inspect stored tokens/cookies
- Rate limiting on sensitive endpoints
- CSRF protection on state-changing operations

### 5. UI Consistency Check

**Component Registry hard check (ui-auditor):**
- Run `node scripts/gen-component-registry.mjs --check`. Non-zero exit → file a Critical bug: either a component lacks its doc block or `docs/components.md` was not regenerated (registry desynced is a process failure). Do not fix it — report it.
- For every new component, search the registry for semantically similar existing components (Button/PrimaryButton, Card/Panel, Badge/Chip/Tag). Flag any that should have been reused instead.
- Visit `/dev/components` showcase route via Playwright or the active agent browser: does every registered component render, in **both** light and dark mode? Does every `## Patterns` entry of `docs/DESIGN-SYSTEM.md` have its `#pattern-<name>` section? Any new component not registered?

Look for the design system baseline at `docs/DESIGN-SYSTEM.md` (rules) plus `docs/components.md` (inventory). If found, audit the implemented UI for violations:

- **Components:** Are existing components used? Check `docs/components.md` for the project-specific component inventory. Flag any one-off styled `<div>` that duplicates a registered component.
- **Colors:** Grep changed files for hardcoded hex values (`#[0-9A-Fa-f]{3,8}` in class names or inline styles). All colors must use the token classes listed in `docs/DESIGN-SYSTEM.md` § Tokens.
- **Radius:** Check border-radius usage matches `docs/DESIGN-SYSTEM.md`. Flag inconsistencies with the project's radius tokens.
- **Typography:** Verify text sizes follow the type scale in `docs/DESIGN-SYSTEM.md` § Scales — no size outside it, no arbitrary values.
- **Spacing:** Check spacing against the scale in `docs/DESIGN-SYSTEM.md` § Scales, not arbitrary pixel values.
- **Focus states:** Tab through interactive elements — verify focus states match `docs/DESIGN-SYSTEM.md`.

Compare against the Component Showcase at `/dev/components` using Playwright or the active agent browser if needed.

### 6. Regression Testing

Using Playwright or the active agent browser, verify existing features still work:

- Navigate to core pages and take snapshots — do they render correctly?
- Execute key user flows of related features
- Check for visual regressions on shared components (compare snapshots)

### 6.4 Simplicity Gate

Before production-readiness is decided, run a focused maintainability pass on the implementation diff since BASE_SHA. This is not a style review; it is a buildability and long-term maintenance gate.

Ken Takahashi is the primary persona feeding this gate, but the gate itself belongs to QA. Marcus may contribute supporting findings, but Ken owns the minimalism lens. Do not run Ken as a second, separate gate; merge his concrete findings into the Simplicity Gate results.

Flag a QA bug when the implementation adds complexity that is not required by the PRDs, architecture, or visible product behavior:

- Premature abstractions: generic frameworks, factories, providers, registries, adapters, plugin systems, or configuration layers with one caller or no clear near-term second use.
- Overbuilt state: duplicated derived state, parallel sources of truth, unnecessary reducers/state machines, excessive context providers, or manual caches where framework/server state is enough.
- Excessive code paths: feature flags, modes, fallbacks, branches, compatibility paths, or options that were not requested and are not needed for safe rollout.
- Duplicated logic/components: new helpers or UI primitives that duplicate existing project utilities, registered components, framework APIs, or straightforward inline code.
- Unclear indirection: wrappers, mappers, service classes, barrel files, hooks, or utility layers that obscure the behavior they contain.
- Dead or speculative code: unused exports, unreachable branches, TODO scaffolding, mock-only pathways, unused props, unused types, or tests that encode behavior the product does not need.

Severity:
- **High:** Complexity materially increases defect risk, blocks confident review/testing, duplicates an established project primitive, or creates a hard-to-change contract.
- **Medium:** Complexity is not release-blocking but should be simplified soon because it adds maintenance cost.
- **Low:** Naming, small cleanup, or local readability issues that do not affect behavior.

For every simplicity bug, include:
- The smallest product requirement that justifies the code.
- The specific code that exceeds that requirement.
- A simplification sketch: delete, inline, merge, reuse existing primitive, collapse state, remove option, or replace custom code with framework/project API.

Critical/High simplicity findings gate production-readiness the same way functional and security bugs do. QA should not mark a PROJ ready while unnecessary complexity is carrying meaningful implementation risk.

### 6.5 Persona Code Review Panel

Spawn **six persona reviewers** on the PROJ's code diff since BASE_SHA. Each persona is a 20-year veteran of a specific discipline. They do **code review**, not browser testing — complementing the Playwright/agent-browser steps above. Findings feed into the bug list AND the `## AGENTS.md Candidates` block (step 7.5). Elena and Ken also write PROJ-level retrospectives.

Note: Ken Takahashi does **not** run per wave. CodeRabbit is the only per-wave review. Ken runs here once against the **assembled PROJ** so the minimalism review can judge cross-wave shape, duplicate abstractions, and code that only looks necessary when each wave is viewed in isolation.

#### The six personas (each: 20 years of experience)

1. **Dr. Sarah Chen — Security Lead (20y)**
   *Focus:* Static/diff threat modeling that complements the runtime Security Audit: OWASP Top 10, auth/session, cryptographic misuse, injection (SQLi/XSS/command/template), secrets in code or logs, CSRF, privilege escalation, insecure deserialization, RLS gaps. Do not duplicate browser probing unless the diff suggests a specific runtime check to add.

2. **Marcus Weber — Principal Engineer (20y)**
   *Focus:* Architecture shape, coupling, naming, error-handling gaps, testability, duplicated domain logic, and premature optimization vs. real performance risk. Marcus may flag unnecessary abstraction when it affects architecture or testability, but component re-invention belongs primarily to UI Consistency and minimalism findings belong primarily to Ken.

3. **Priya Sharma — Performance Engineer (20y)**
   *Focus:* Latency hotpaths, N+1 queries, unbounded work (loops, recursion, memory), bundle size, render-blocking, cache keys, pagination correctness, cold-start cost.

4. **Thomas Mueller — SRE / Reliability Engineer (20y)**
   *Focus:* Failure modes (network, disk, partial writes), retries/backoff, idempotency, timeouts, observability (logs/metrics/traces), graceful degradation, rollback/backfill safety, race conditions, resource leaks.

5. **Elena Rodriguez — Principal Architect, PROJ Retrospective (20y)**
   *Focus:* **Cross-wave, PROJ-level patterns** that per-wave reviews can't catch. Did the waves add up to a coherent feature, or did they silt up into tech debt? Which abstractions emerged that should have been planned? Which features grew faster than the PRD promised (scope creep)? Are we building on a foundation that will hold the next PROJ, or painted ourselves into a corner? Elena does not redesign the architecture during QA; she reports coherence risks and next-PROJ lessons.
   *Deliverable:* two parts — (a) findings like the others (Critical/High/Medium/Low), and (b) a **PROJ Retrospective** narrative: "Given what we learned building PROJ-X, what should change for PROJ-X+1?" Appends to `5_progress/PROJ-<X>-progress.md` under a new `## PROJ Retrospective` section (not an AGENTS.md candidate — too long-form for one line).

6. **Ken Takahashi — Minimalism Engineer (20y)**
   *Focus:* Primary reviewer for the Simplicity Gate: PROJ-level YAGNI, premature abstraction, layers with one caller, duplicate utilities/components, feature flags/options that the PRD did not require, dead paths, and code that could be deleted because the assembled feature found a simpler shape. Ken must turn meaningful over-complexity into concrete QA bugs with simplification sketches, not only retrospective advice.
   *Deliverable:* two parts — (a) findings like the others (Critical/High/Medium/Low), and (b) a **Minimalism Retrospective** narrative: "What should we delete, inline, merge, or avoid in PROJ-X+1?" Append this under `## PROJ Retrospective` with source `Ken Takahashi (Minimalism)`.

Use **exactly these names and disciplines** — they are stable across runs so the user recognizes recurring reviewers. The 20-year framing matters: each persona should call out risks that would embarrass a senior engineer, not nitpicks a junior might raise.

#### Invocation: Claude-native

Default path: if Claude subagents are available, spawn six independent review subagents in parallel, one per persona. Do this before running any persona review locally.

Hard rules:
- Spawn exactly six persona review subagents: Chen, Weber, Sharma, Mueller, Rodriguez, Takahashi.
- Give each subagent only one persona. Do not ask one subagent to cover multiple personas.
- Run the six subagents in parallel when the tool supports it. Do not serialize them unless parallel spawning is unavailable.
- Keep the main agent as orchestrator: it launches, waits, deduplicates, assigns BUG-IDs, and writes summaries.
- Do not paste raw diffs or long logs into the main context if a subagent can inspect them directly.
- Only use the local sequential fallback when subagent delegation is unavailable or prohibited by the active Claude instructions.

Spawn one Claude `Agent` subagent per persona, normally with `subagent_type: general-purpose`. Prompt each subagent with:
- Persona identity (for example, "You are Dr. Sarah Chen, 20y Security Lead, ex-OWASP …")
- Discipline focus (same bullet list as above)
- Scope: `git diff BASE_SHA..HEAD` (whole PROJ)
- Expected output format:
  - Chen/Weber/Sharma/Mueller: Critical/High/Medium/Low findings with file:line + optional `AGENTS.md` one-liners
  - Elena: findings **plus** a separate PROJ Retrospective narrative (5-15 bullets)
  - Ken: findings **plus** a separate Minimalism Retrospective narrative (5-15 bullets)

Required subagent tasks:
- **Dr. Sarah Chen:** static/diff security review. Output security findings and suggested runtime checks only when needed.
- **Marcus Weber:** principal engineering review. Output architecture, coupling, error-handling, testability, and duplicated domain logic findings.
- **Priya Sharma:** performance review. Output latency, N+1, unbounded work, bundle, cache, pagination, and cold-start findings.
- **Thomas Mueller:** reliability review. Output failure-mode, retry, idempotency, timeout, observability, race, and resource-leak findings.
- **Elena Rodriguez:** cross-wave architecture coherence review plus PROJ Retrospective.
- **Ken Takahashi:** Simplicity Gate review plus Minimalism Retrospective, with simplification sketches for every concrete finding.

Launch all six in one parallel batch when possible. Record the subagent IDs, wait for all six reports, then merge findings. If delegation is not available, run the six reviews sequentially in the main session using focused diffs and searches. Keep each persona report concise and merge findings immediately into the QA result.

#### Merging findings

After all six persona reviews complete:

1. **Deduplicate:** If two personas flag the same root cause, merge them (keep the higher severity, list both personas in `source:`).
2. **Assign stable IDs:** Every finding gets an ID `BUG-PROJ<X>-QA-<NNN>` where `<NNN>` is zero-padded sequential within this QA run (001, 002, …). Every AGENTS.md candidate gets `AGENTS-PROJ<X>-QA-<NNN>`. IDs are the reference handle for fixer-spawns and for status tracking — line numbers drift when multiple fixers run, IDs don't.
3. **Bugs:** Append each finding to the QA bug list. Format per entry:
   ```markdown
   ### BUG-PROJ1-QA-007 — [High] XSS in comment render
   - **File:** `src/features/comments/CommentCard.tsx`
   - **Anchor:** `export function CommentCard` (symbol/regex — not a line number)
   - **Source:** Dr. Sarah Chen (Security) + Marcus Weber (Principal)
   - **Status:** open
   - **Fix attempts:** 0
   - **Description:** …
   - **Repro:** …
   - **Fix sketch:** …
   ```
4. **AGENTS.md candidates:** Append to `## AGENTS.md Candidates` in `5_progress/PROJ-<X>-progress.md`:
   ```markdown
   - [PROPOSED] AGENTS-PROJ1-QA-003: <one-liner rule> — source: Priya Sharma (Performance)
   ```
   Skill 7 flips `[PROPOSED]` → `[MERGED]` or `[REJECTED]` by ID, preserving the line. No deletions — the log is append-only.
5. **PROJ Retrospective (Elena + Ken):** Append Elena's and Ken's narratives verbatim to `5_progress/PROJ-<X>-progress.md` under `## PROJ Retrospective` (no IDs — long-form). Prefix each subsection with the persona name.

**Why anchors, not line numbers:** parallel fixers on the same file shift line numbers. An anchor (`export function validateSession` or regex) stays stable because fixers re-lookup before editing.

**Fixer spawn format — parallel when safe:**

1. **Cluster bugs by `file` field.** Bugs touching the same file go into one cluster (sequential within, because parallel edits on the same file race regardless of anchors).
2. **Run clusters in parallel only when safe and allowed.** If Claude delegation is allowed, spawn one `micro-fixer` worker per disjoint file cluster. Otherwise hand the clusters back to implementation or fix locally only after the user explicitly asks for fixes.
3. **Each worker prompt or local fix task contains only:**
   - The BUG-IDs + anchors for its cluster
   - The relevant feature's `agent.md` excerpt
   - For simplicity bugs: the required reduction target (delete, inline, merge, reuse, collapse state, remove option) and the rule that the fix should reduce code/indirection before adding new code
   - A verify-before-claiming-done reminder: run the check, read the actual output, only then report status
   - ≤ 2000 tokens total
4. **Disjoint-file invariant:** if clustering leaves bugs that span multiple files, assign to the primary file's cluster and document the cross-file touch in the prompt. Never split a single bug across subagents.
5. **Lead-owned control plane:** the lead alone updates `progress.md`, stages, and commits while parallel fixers run.

The main agent collects reports from all fixers, verifies that simplicity fixes actually remove or collapse unnecessary code, updates each BUG-ID's `status` (to `fixed` or `open` + `fix_attempts += 1`), and re-runs the affected tests. Only after all clusters return does the main agent decide on re-spawns for still-failing bugs.

Example: 12 bugs in a QA run across 7 files → 7 parallel fixer-spawns (one per file). Wall-clock time drops from 12 × T to ~max(T_per_file).

Persona retrospectives are **advisory**. Persona bug findings are normal QA findings once accepted into the merged bug list; Critical/High persona bugs gate release through the same severity rules as browser, security, UI, regression, and simplicity findings.

### 7. Document Results

For each PRD tested: append a `## QA Test Results` section to that PRD file (`specs/PROJ-<X>-<theme>/2_PRDs/PROJ-<X>-PRD-<Y>-<desc>.md`) using `references/test-template.md` as the format.

Also update `specs/PROJ-<X>-<theme>/5_progress/PROJ-<X>-progress.md` with a top-level QA summary across all PRDs.

Include for each tested AC:
- What was done in the browser (steps)
- What was observed (snapshot/screenshot evidence)
- PASS or FAIL with details

Also document the `### Simplicity Gate Results` for the PROJ:
- Files or modules inspected in the diff
- Any High/Medium/Low simplicity bugs, with BUG-IDs
- Explicit statement if no release-blocking complexity was found
- Simplification candidates that should become AGENTS.md rules if they are project-wide and repeatable

Also document `### Sonar Quality Input`:
- `ran` with counts by severity, or `skipped` with the exact reason from Skill 5
- Any Sonar findings promoted to QA bugs, with BUG-IDs
- Explicit statement when Sonar was skipped and therefore not considered release-blocking

**Findings ledger (framework runs):** when `scripts/ledger.mjs` exists,
additionally emit every bug as a ledger record — one JSON line per bug
piped to `node scripts/ledger.mjs add <X> <theme>` with
`source: "qa"`, the normalized severity, the file plus symbol **anchor**
(not a line number), and the BUG-ID in the summary. The ledger is the
single fix queue the P6 controller works from; markdown bug entries
stay the human-readable evidence, never a second queue.

### 7.5 AGENTS.md Candidates

While testing, collect project-wide rules that future agents should know. These become candidates — not direct edits — for the project-root `AGENTS.md`. Skill 7 (documentation) asks the user to approve each candidate before merging. Do not propose durable rules for `CLAUDE.md`; that file is pointer-only and must only tell Claude to read `AGENTS.md`.

**Strict filter — all three criteria must hold:**

1. **Repeat-risk:** A future agent lacking this info would make the same mistake again.
2. **Project-wide:** Applies to more than one feature/PROJ, not just this one.
3. **Compressible:** Fits in one line (≤ 120 characters).

Typical sources during QA:
- A bug that recurs across features (e.g. unsafe cookie flags)
- A convention QA discovered the implementation violated repeatedly (e.g. missing RLS on new tables)
- A platform quirk that tripped red-team-tester or ui-auditor (e.g. `bcrypt` salt-rounds threshold)

**Append candidates to the `## AGENTS.md Candidates` section** of `specs/PROJ-<X>-<theme>/5_progress/PROJ-<X>-progress.md`. If the section does not exist yet, create it. Do NOT write to `AGENTS.md` directly — Skill 7 does the merge after user approval. Never write durable rules to `CLAUDE.md`.

Format:

```markdown
## AGENTS.md Candidates
- [PROPOSED] <one-liner rule>                        — source: QA BUG-3
- [PROPOSED] <another convention>                    — source: QA regression check
```

Skill 5 quality-gate agents (code-reviewer-gate, optional sonar-cli stream, red-team-tester, ui-auditor) may already have added entries to this section — QA adds on top, not overwriting. Omit the section entirely if no candidates emerged.

### 8. Present Summary

Report to the user:

- Total acceptance criteria: passed / failed
- Bug count by severity
- Security findings
- Simplicity gate findings and whether any release-blocking complexity remains
- Sonar quality input: ran/skipped, blocking findings promoted to QA bugs
- **QA persona cross-review:** provider, six persona results, degraded status, round result, and promoted findings. If degraded, tell the user that Claude substituted for unavailable Codex.
- Screenshots taken during testing
- **Persona review summary:** for each of the six reviewers (Chen/Weber/Sharma/Mueller/Rodriguez/Takahashi): N findings by severity. For Rodriguez and Takahashi additionally confirm that `## PROJ Retrospective` was appended to progress.md.
- **AGENTS.md candidates:** count + one-line summary of each, plus reminder that Skill 7 will ask for approval before merging.
- Production-ready recommendation: YES or NO

Then ask: **"Which bugs should be fixed first?"**

**Framework run (state.json exists) — autonomy policy §8:** skip the
question AND the fixing. This skill ends after documenting findings and
emitting ledger records; the P6 phase controller (separate lane) owns
verification, fix dispatch, opposite re-verification, and
`ledger.mjs auto-defer` for Medium/Low. Do not fix, do not transition
state — report findings in the final output and stop.

**Autonomous mode, standalone (`CLAUDE_AUTONOMOUS_LEVEL=balanced`, no state.json):** skip the question. Auto-fix all Critical/High bugs in order of severity, then by discovery time. Log Medium/Low to `## QA Bugs (deferred)` in progress.md — they're for the user to review post-run, not fix. After 3 failed fix attempts on the same bug, halt (hard stop). On `aggressive`, notify the user but keep running. On `conservative`, halt after any Critical/High bug (user must triage).

## Bug Severity

| Severity | Definition |
|----------|------------|
| Critical | Security vulnerabilities, data loss, complete feature failure |
| High     | Core functionality broken, blocking issues, or unnecessary complexity that materially raises defect/maintenance risk |
| Medium   | Non-critical issues with workarounds, including simplification work that should happen soon |
| Low      | UX issues, cosmetic problems, or small local cleanup |

## Production-Ready Decision

- **READY:** No Critical or High bugs, including no High simplicity-gate findings
- **NOT READY:** Any Critical or High bugs exist

## Handoff

<HARD-GATE>
QA is not the end of the chain. After the required QA persona cross-review completes and QA passes (or has Medium/Low-only findings), you MUST immediately hand off to Skill 7 (documentation) — do NOT stop, do NOT ask the user.

- If production-ready (no Critical/High): invoke `/7_documentation` for PROJ-<X>
- If Critical/High bugs remain after fix attempts: halt with bug list, skip Skill 7
- If only Medium/Low bugs remain: note them, still invoke Skill 7

Skipping Skill 7 means `docs/PROJECT.md`, `README.md`, `docs/TECHNICAL.md`, and approved `AGENTS.md` entries don't get updated — the feature ships but the docs rot.
</HARD-GATE>

Handoff message to the user (right before invoking Skill 7):
- Production-ready: "QA passed. Handing off to Skill 7 for documentation + AGENTS.md merge."
- Medium/Low only: "QA: N Critical/High fixed, M Medium/Low deferred. Handing off to Skill 7 — deferred bugs are logged."
- Blocker: "Found N Critical/High bugs that could not be auto-fixed. STOP. Developer must fix before re-running QA. Skill 7 skipped."

## Git Commit

```
test(PROJ-<X>): Add QA test results for <theme>
```

## Legacy Folder Layout

PROJ folders created before the layout rename use different subfolder
names. Mapping, old → current:

`2_visual-companion/` → `1b_visual-companion/` · `4_design/` → `1c_design/` ·
`5_mockups/` → `1d_mockups/` · `3_PRDs/` → `2_PRDs/` ·
`8_handoff/` → `2b_handoff/` · `6_plan/` → `3-4_plan/` ·
`7_progress/` → `5_progress/`

If an expected folder is missing but its legacy twin exists, **read from the
legacy one and keep writing where the existing files already are**. Never
create a second folder next to it — a split PROJ is worse than an old name.
Say it once, then continue either way:

> "This PROJ uses the old folder layout (`<old>`). Rename the folders to the
> current names, or continue with the existing layout?"

Renaming is a `git mv` per folder plus a search for the old paths in the
PROJ's own documents. It is never a precondition for this skill.