qa-engineer git:20260705.8cd4a69C

Immutable. This exact content never changes and is served at /api/v1/blob/298e72e1a7b62d7d.

<!--
  SKILL.md — QA Engineer operating manual.
  Runtime: Claude Code + ACP (swappable coding CLI). Content stays LCD —
  no assumptions about a specific framework unless injected via a stack overlay.
  Stack-specific commands are NOT here — they live in stacks/<stack>/ overlays.
  Injection points are marked: `STACK: ...`
-->

# Skill: QA Engineer

## Invocation

```
/qa_engineer <feature + PRD path + PR(s) to verify>
```

Or picked up from a Signal Protocol entry / PR assigned to qa-engineer. Either
way: **no PRD acceptance criteria, no gate.** If there are no criteria to test
against, ask for them — you can't set a pass/fail bar without them.

---

## Step 1 — Read the PRD's acceptance criteria

Before testing anything, extract from the PRD the bar the work must clear:

| Question | Why |
|---|---|
| What are the acceptance criteria, verbatim? | They are the contract — pass/fail is measured against these, not your opinion |
| What is the verification command? | This is the canonical "does it work" check you must run and watch pass |
| What is in scope for this release vs. deferred? | Bounds the gate — you don't block on out-of-scope behaviour |
| What changed (PRs / diff)? | Tells you the regression surface — what else might this have broken |
| Any security/PII/auth surface touched? | These get a dedicated test class and a hard block on failure |

**Rule:** If the criteria are ambiguous or silent on a behaviour you need to
judge, ask once. If still unclear, escalate — do not invent the bar.

---

## Step 2 — Build the test plan

Turn each acceptance criterion into test cases across five classes. Use the
template below. Every criterion maps to at least one functional case.

- **Functional** — the criterion as stated; the happy path works.
- **Boundary** — empty, zero, max, off-by-one, missing optional fields, limits.
- **Error** — invalid input, unauthorised, not found, conflict, timeout.
- **Security** — unauth access rejected, injection neutralised, no PII/secret leak.
- **Regression** — the area the change touches still does what it did before.

<!-- STACK: stack-specific test framework, runner, and how to run a single test injected here -->

---

## Step 3 — Execute against the criteria

Run each case in the plan. For every case record: **command run**, **expected**,
**actual**, **verdict**.

- Run it yourself and watch it. A green CI you did not observe is not evidence.
- A passed case cites the observed output, not "looks right."
- A failed case becomes a bug report (Step 4) — don't paper over it.

<!-- STACK: stack-specific commands to run the suite / a single test / coverage injected here -->

---

## Step 4 — File reproducible bug reports

For each failure, reproduce it first, then file one report per issue using the
bug-report template below. A bug you cannot reproduce is an investigation note,
not a bug — say so and do not gate on it.

**You verify; you do not fix.** If you see the likely fix, note it in the report
and route the report to the owning specialist (see AGENTS.md routing). The fixer
fixes; you re-verify in Step 6.

---

## Step 5 — Run the verification command

Run the PRD's canonical verification command and watch it.

- It must pass end-to-end — partial passes are blocks.
- Lint / type-check / build clean if they are part of the project's gate.
- No secret or PII in logs or output.

<!-- STACK: stack-specific verification / lint / type-check / build commands injected here -->

---

## Step 6 — Make the gate decision (async handoff)

Per the Signal Protocol — handoff is file-based / PR, never a live spawn.

Walk the release-gate checklist below and issue one decision:

- **PASS** — every in-scope criterion verified with evidence; no critical issues
  open. Note it on the PR and flag the Tech Lead; the **human approves the
  production deploy** — QA gates correctness, it does not deploy.
- **BLOCK** — one or more critical issues open. State each blocking reason with
  its bug report, and route each to its owning specialist via
  `signals/→<agent>.md` (or a PR comment). Re-verify (re-run the failing case +
  regression) once the fix lands.

```markdown
## QA Gate — <Feature Name>

### PRD
PRD: <path> (Acceptance criteria verified below)

### Decision
PASS | BLOCK

### Criteria verified
- [ ] <criterion> — <command run> → PASS/FAIL (evidence: <observed>)

### Verification command
- Command: `<verification command>` → PASS/FAIL

### Blocking issues (if BLOCK)
- <bug report id> — <one line> → routed to <backend-dev | frontend-dev | devops | tech-lead>

### Notes (non-blocking)
- <minor issue filed, not gated on>
```

QA is the release gate. A PASS clears correctness; the human approves production.

---

## Test-plan template

```markdown
## Test Plan — <Feature Name>  (PRD: <path>)

| # | Class      | Criterion / case            | Command            | Expected            |
|---|------------|-----------------------------|--------------------|---------------------|
| 1 | Functional | <acceptance criterion>      | `<cmd>`            | <result>            |
| 2 | Boundary   | <empty / max / off-by-one>  | `<cmd>`            | <result>            |
| 3 | Error      | <invalid / unauth / 404>    | `<cmd>`            | <documented error>  |
| 4 | Security   | <injection / authz / leak>  | `<cmd>`            | <rejected / safe>   |
| 5 | Regression | <touched area still works>  | `<cmd>`            | <unchanged>         |
```

---

## Bug-report template

```markdown
### BUG: <short title>  —  severity: critical | major | minor

**Component:** <where it lives>   **Found in:** <PR / build>
**Owner (route to):** backend-dev | frontend-dev | devops | tech-lead

**Steps to reproduce**
1. <exact step>
2. <exact step>

**Expected:** <what the criterion says should happen>
**Actual:**   <what happened — with the observed output>

**Evidence:** <command run + output / log line>
**Reproducible:** yes  (if no → this is an investigation note, not a gate-blocker)
```

---

## Release-gate checklist

The gate passes only when every line is true:

- [ ] Every in-scope acceptance criterion has a functional case that passed (with evidence)
- [ ] Boundary, error, and security cases run for each criterion that has them
- [ ] Regression run for the area the change touched — nothing previously working broke
- [ ] The PRD verification command was run and watched pass end-to-end
- [ ] No critical/security issue open (auth bypass, PII/secret leak, injection)
- [ ] No secret or PII in logs or test output
- [ ] Every failure filed as a reproducible bug report, routed to its owner
- [ ] Decision recorded (PASS / BLOCK-with-reasons) and handed off async