---
name: scorpio-qa-final
description: Final-pass QA review — cross-task integration testing, UI validation via browser MCP (Playwright), and overall quality assessment. Use after scorpio-qa has validated individual tasks, as the last quality gate before release.
---

# QA Reviewer (Final Pass)

The final quality gate before release. This skill focuses on what per-task reviews cannot catch: cross-task integration, UI behavior, and overall feature coherence. Individual task correctness should already be validated by **scorpio-qa** before this skill runs.

> **Model role — review.** This skill runs the pipeline's **review** phase, so it targets the configured `{models.review}` (model + optional `effort`) when `scorpio.config.json` sets it — falling back to `{models.default}` → the harness's main-session model. Per-role model selection is a **declaration honored to the granularity the harness supports** (the `modelSelection` capability): on Claude Code it's advisory (the Agent tool can't pick a model per dispatch from config) — state the intended model and apply it via agent frontmatter `model:` or `CLAUDE_CODE_SUBAGENT_MODEL`; the Claude Agent SDK honors it per agent-definition. See [docs/CONFIG.md](../../docs/CONFIG.md#per-role-models).

## Session Management Rules

- **Max 3 tasks per session.** If reviewing more, batch into multiple sessions.
- **Subagents write to files, return summaries.** QA reports go to disk. Return only: task ID, result, finding count, report path.
- **One pipeline phase per session.** Do not auto-chain into scorpio-qa-rework.

## Prerequisites

Before reviewing, you need:
- Completed task(s) that have passed **scorpio-qa** (per-task review already done)
- Task QA reports in `{docs.qaReports}/TASKQA-*.md`
- Access to the git diff of changes made
- **`PROJECT-CONTEXT.md`** (if present) — read it first for the project's conventions, architecture boundaries, and security/safety rules, so this final pass can flag violations of the project's *own* standards, not just generic issues. It's a concise summary, so this stays cheap. (The per-task **scorpio-qa** stays lean and skips this; the final pass is where it belongs.)
- Browser MCP (Playwright) available for UI testing (auto-skipped if not applicable)

## QA Review Phases

```
Phase 1: Prepare     → Generate QA test parameters from acceptance criteria
Phase 2: Code Review → Review diff for correctness, patterns, security
Phase 3: UI Review   → Browser-based validation of user-facing behavior (auto-skipped if no UI)
Phase 4: Report      → Produce structured QA report with findings
```

## Phase 1: Prepare

### Generate QA Test Parameters

For each acceptance criterion in the task, expand into specific test cases:

```markdown
## QA Test Parameters

### From Acceptance Criteria

| AC # | Criterion | Test Case | Input/Action | Expected Result | Type |
|------|-----------|-----------|--------------|-----------------|------|
| AC-1 | User can submit form and sees success message | Submit valid form | Fill all required fields, click Submit | Success toast appears, form resets | UI |
| AC-2 | API returns 400 for invalid input | Send malformed request | POST with missing required field | 400 response with error details | Code |
| AC-3 | Existing tests pass | Run test suite | `npm test` or equivalent | All tests green | Code |
| AC-4 | New tests added for share feature | Check test files | Review test files in diff | Tests cover happy path + edge cases | Code |
```

**Honesty rule — a runtime criterion you couldn't execute is NOT VERIFIED, not PASS.** If a test case requires actually running the app/tool/test and you couldn't (runtime/engine/tool absent, app not started), record it as **NOT VERIFIED** with the reason and surface it in the verdict — never upgrade a static/structural inspection to a PASS. A behavior claim needs the behavior observed; "the code looks right" is not the same as "it ran."

### Auto-Detect QA Mode

Determine which phases to run based on task signals:

| Signal | QA Mode |
|--------|---------|
| Task modifies `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html`, or `.css` files | **code + ui** |
| Task has UI-related acceptance criteria (renders, displays, shows, clicks, navigates) | **code + ui** |
| Task is API-only, backend, database, CLI, or infrastructure | **code-only** |
| Task spec includes `QA Mode: code-only` override | **code-only** |
| Task spec includes `QA Mode: code+ui` override | **code + ui** |

When in doubt, check the git diff for UI file changes. If none exist, default to code-only.

## Phase 2: Code Review

Review all changed files with a structured checklist. Ground the **Patterns** and **Security** checks in `PROJECT-CONTEXT.md` (the project's conventions + security/safety posture) so you catch deviations from the project's own standards, not just generic ones.

### Identify the Diff

Use git to isolate what changed for this task:

```bash
# Option A: Diff from base branch
git diff [base-branch]...HEAD -- [files from task]

# Option B: Specific commits for this task
git log --oneline  # find the relevant commits
git diff [before-commit]..[after-commit]

# Option C: If task recorded its commits
git show [commit-hash]
```

### Code Review Checklist

| Category | Check | Severity if Failed |
|----------|-------|--------------------|
| **Correctness** | Does the code do what the task specifies? | Critical |
| **Correctness** | Are edge cases handled? | High |
| **Correctness** | Are error paths handled appropriately? | High |
| **Patterns** | Does the code follow existing codebase conventions? | Medium |
| **Patterns** | Are naming conventions consistent with the project? | Low |
| **Security** | No hardcoded secrets, tokens, or credentials? | Critical |
| **Security** | Input validation present on all external inputs? | High |
| **Security** | No SQL injection, XSS, or command injection vectors? | Critical |
| **Performance** | No obvious N+1 queries or unbounded loops? | Medium |
| **Performance** | Appropriate use of caching, pagination, or async? | Medium |
| **Testing** | New tests added for new functionality? | High |
| **Testing** | Existing tests still pass? | Critical |
| **Testing** | Edge cases covered in tests? | Medium |
| **Dependencies** | No unnecessary new dependencies introduced? | Medium |
| **Dependencies** | No known security vulnerabilities in new deps? | High |
| **Completeness** | All acceptance criteria addressed in code? | Critical |
| **Completeness** | No TODOs, FIXMEs, or placeholder code left behind? | Medium |
| **Completeness** | No debug logging or console statements left in? | Low |

### Run Quality Gates

Execute the project's quality gate commands and record results:

```markdown
## Quality Gate Results

| Gate | Command | Result |
|------|---------|--------|
| Lint | `npm run lint` (or equivalent) | PASS / FAIL |
| Type Check | `npm run typecheck` (or equivalent) | PASS / FAIL |
| Unit Tests | `npm test` (or equivalent) | PASS / FAIL |
| Build | `npm run build` (or equivalent) | PASS / FAIL |
```

If any gate fails, record it as a Critical finding.

### Document Code Findings

For each issue found:

```markdown
### Finding: [CR-NNN] [Title]

**Severity**: Critical | High | Medium | Low
**Category**: Correctness | Security | Performance | Patterns | Testing | Completeness
**File**: `path/to/file.ts:line`

**Issue**:
[What's wrong — be specific]

**Code**:
```language
[relevant code snippet]
```

**Expected**:
[What should be there instead]

**Recommendation**:
[How to fix it]
```

## Phase 3: UI Review

Use browser MCP (Playwright) to validate user-facing behavior. **This phase is auto-skipped for code-only tasks.**

### UI Review Process

1. **Start the application** — Ensure the dev server is running
2. **Navigate to the feature** under test
3. **Execute each UI test case** from the QA Test Parameters (Phase 1)
4. **Capture evidence** — Take screenshots for both pass and fail states
5. **Check the browser console** — Look for JavaScript errors or warnings

### Browser MCP Interactions

Use the browser MCP tools to interact with the application:

```
1. Navigate:    browser_navigate(url)
2. Click:       browser_click(selector)
3. Type:        browser_type(selector, text)
4. Screenshot:  browser_screenshot()
5. Read text:   browser_get_text(selector)
6. Check state: browser_is_visible(selector)
7. Wait:        browser_wait_for(selector)
8. Console:     browser_console_messages()
```

Adapt tool names to match your specific browser MCP server implementation.

### UI Review Checklist

| Category | Check | Severity if Failed |
|----------|-------|--------------------|
| **Functional** | Feature works as specified in acceptance criteria | Critical |
| **Functional** | Happy path completes without errors | Critical |
| **Functional** | Error states display appropriate messages | High |
| **Functional** | Loading states appear during async operations | Medium |
| **Visual** | Layout is not broken or misaligned | High |
| **Visual** | Matches existing design patterns and style | Medium |
| **Visual** | Responsive behavior is acceptable (if applicable) | Medium |
| **Interaction** | Buttons and links are clickable and respond | High |
| **Interaction** | Forms validate input correctly | High |
| **Interaction** | Navigation works as expected | High |
| **State** | Page handles empty or null data gracefully | Medium |
| **State** | Refreshing the page preserves expected state | Medium |
| **Accessibility** | Interactive elements are keyboard accessible | Medium |
| **Console** | No JavaScript errors in browser console | High |

### Document UI Findings

For each issue found:

```markdown
### Finding: [UI-NNN] [Title]

**Severity**: Critical | High | Medium | Low
**Category**: Functional | Visual | Interaction | State | Accessibility
**Page**: [URL or route path]
**Screenshot**: [reference to captured screenshot]

**Steps to Reproduce**:
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Observed**: [What happened]
**Expected**: [What should happen]

**Recommendation**:
[How to fix it]
```

## Phase 4: Report

Produce a structured QA report combining all findings.

### QA Report Format

```markdown
# QA Report: [TASK-ID] [Task Title]

## Summary
- **QA Mode**: Code + UI | Code Only
- **Overall Result**: PASS | FAIL | PASS WITH NOTES
- **Findings**: [N] total — [N] Critical, [N] High, [N] Medium, [N] Low
- **Date**: [date]

## Quality Gate Results

| Gate | Command | Result |
|------|---------|--------|
| Lint | [command] | PASS / FAIL |
| Type Check | [command] | PASS / FAIL |
| Unit Tests | [command] | PASS / FAIL |
| Build | [command] | PASS / FAIL |

## Acceptance Criteria Results

| AC # | Criterion | Result | Evidence |
|------|-----------|--------|----------|
| AC-1 | [criterion text] | PASS | [brief evidence] |
| AC-2 | [criterion text] | FAIL | See Finding CR-001 |
| AC-3 | [criterion text] | PARTIAL | [explanation] |

## Test Parameter Results

| Test # | Test Case | Result | Notes |
|--------|-----------|--------|-------|
| TP-1 | [test case] | PASS | |
| TP-2 | [test case] | FAIL | [brief note] |

## Code Review Findings

### [Finding details as documented in Phase 2]

## UI Review Findings

### [Finding details as documented in Phase 3]

(Or: "UI review skipped — code-only task")

## Recommendation

**[APPROVE | REWORK REQUIRED | BLOCKED]**

[1-2 sentences explaining the recommendation]

### Rework Items (if applicable)
1. [Critical/High finding requiring fix]
2. [Critical/High finding requiring fix]

### Deferred Items (if applicable)
- [Medium/Low findings that could be addressed later]
```

### Result Classification

| Result | Criteria |
|--------|----------|
| **PASS** | All acceptance criteria met, no Critical or High findings, all quality gates pass |
| **PASS WITH NOTES** | All acceptance criteria met, only Medium/Low findings |
| **FAIL** | Any acceptance criterion not met, OR any Critical/High finding, OR quality gate failure |

## QA Report File Organization

Store QA reports alongside task files:

```
docs/
├── tasks/
│   ├── TASK-INDEX.md
│   ├── CORE-001.md
│   ├── done/
│   │   └── CORE-001.md
│   └── qa-reports/
│       ├── QA-CORE-001.md
│       └── QA-UI-002.md
```

## Batch Review Mode

When reviewing multiple tasks from a single scorpio-execute session:

1. Review each task individually
2. Produce per-task QA reports
3. Generate a batch summary:

```markdown
# QA Batch Summary

## Session: [date or identifier]

| Task | Result | Critical | High | Med | Low |
|------|--------|----------|------|-----|-----|
| CORE-001 | PASS | 0 | 0 | 1 | 0 |
| UI-002 | FAIL | 1 | 2 | 0 | 1 |
| API-003 | PASS w/NOTES | 0 | 0 | 2 | 3 |

**Overall**: 1 of 3 tasks require rework
```

## What NOT To Do

- Do not approve tasks with failing acceptance criteria
- Do not skip UI review when the task has user-facing changes
- Do not report findings without evidence (file path, screenshot, reproduction steps)
- Do not mix severity levels — a security vulnerability is always Critical
- Do not block shipping on Low-severity cosmetic issues alone
- Do not modify or fix code during review — fixes go through rework tasks
- Do not generate vague findings ("Code could be better")
- Do not re-review unchanged code from prior tasks

## Subagent Return Discipline

If using subagents to review individual tasks, each subagent must:
1. Write the full QA report to `{docs.qaReports}/QA-[TASK-ID].md`
2. Return ONLY this summary to the parent:
   ```
   TASK-ID: [ID]
   Result: PASS | FAIL | PASS WITH NOTES
   Findings: [N] Critical, [N] High, [N] Medium, [N] Low
   Report: {docs.qaReports}/QA-[TASK-ID].md
   ```

**Do not return full report contents to the parent session.**

## Skill Chain

This skill is the final quality gate in the QA pipeline:

1. **scorpio-execute** → Execute implementation tasks
2. **scorpio-qa** → Per-task code review and AC validation
3. **scorpio-qa-final** → Final pass: integration, UI, cross-task review (you are here)
4. **scorpio-qa-rework** → Triage findings, generate rework tasks
5. **scorpio-execute** → Execute rework tasks
6. Repeat until all tasks pass or escalate after 3 cycles

**Each step should be a separate session** to manage context effectively.

## Next Steps

After producing the QA report, use **scorpio-qa-rework** in a new session to:
1. Review and classify each finding
2. Generate rework tasks for any FAIL results
3. Route rework tasks back to **scorpio-execute**