---
name: scorpio-qa
description: Per-task code review that validates acceptance criteria, checks correctness, and catches bugs immediately after implementation. Use after scorpio-execute completes each task, before the final-pass scorpio-qa-final.
---

# Task QA

A focused, per-task quality check that runs immediately after implementation. This skill replaces the lightweight "self-QA" step with a structured review that validates acceptance criteria and catches bugs — while staying lean enough to complete within a single subagent session.

> **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).

## Purpose

Task QA is the **first quality gate** after implementation. It catches issues per-task so they can be fixed cheaply, before the broader final-pass QA review.

| Task QA (this skill) | scorpio-qa-final (final pass) |
|---|---|
| Per-task, runs after each task | Runs after a batch of tasks |
| Reviews the diff for ONE task | Reviews cross-task integration |
| Validates acceptance criteria | Validates overall feature behavior |
| Code correctness and security | UI testing via browser MCP |
| Writes report to file | Writes report to file |
| Lightweight, fast | Thorough, slower |

## Prerequisites

- A completed task from **scorpio-execute** (implementation done; may be uncommitted)
- The original task specification (`{docs.tasks}/[TASK-ID]*.md`)
- The implementation report (`{docs.tasks}/done/[TASK-ID]-report.md`) if present

## Review Process

```
Step 1: Read    → Read task spec + implementation report + minimal code (nothing else unless necessary)
Step 2: Check   → Validate against checklist
Step 3: Report  → Write pass/fail report to file
```

## Step 1: Read

Read ONLY what's needed for this specific task:

1. **The task spec** — acceptance criteria, description, technical notes
2. **The scorpio-execute report** — what it claims changed and which gates passed
3. **The minimal code surface** needed to verify the acceptance criteria:
   - Prefer reading only the files listed in the report's “Files changed”
   - If a file is long, read only the relevant section using line offsets

Optional (read-only): if `git` is available and the user permits, you may use `git diff` to focus the review. Do not require commits.

**Scope discipline:** Do NOT read PROJECT-CONTEXT.md, do NOT explore the codebase, do NOT read unrelated files. The task spec + report + minimal code surface should be enough for a per-task review.

If you must understand a type or import to validate correctness, read ONLY the specific file and section needed — use line offsets, not full file reads.

## Step 2: Check

Validate the diff against this checklist:

### Acceptance Criteria Validation

For each acceptance criterion in the task spec:
- Is it addressed in the code changes?
- Can you verify it from the diff?
- Mark: PASS / FAIL / UNCLEAR / **NOT VERIFIED**

**Honesty rule — never inflate a structural check into a PASS.** If a criterion asserts *runtime* behavior ("opens without errors", "renders", "the endpoint returns 200") and you could not actually execute it — the engine/tool/runtime isn't installed, the app wasn't run, the test couldn't be invoked — mark it **NOT VERIFIED** with the reason, **not PASS**. A static/structural read ("the project file looks valid") is evidence the *code* is plausible, not proof the *behavior* holds; say exactly that. Surface every NOT VERIFIED in the report so the orchestrator can decide whether it blocks close or needs a runtime/human check — a criterion silently passed on inspection is a false green.

### Correctness Check

| Check | Look For |
|-------|----------|
| Logic | Does the code do what the task describes? |
| Edge cases | Null checks, empty arrays, boundary conditions |
| Error handling | Are errors caught and handled appropriately? |
| Return values | Do functions return what callers expect? |
| Async | Are promises awaited? Race conditions? |

### Security Check (quick scan)

| Check | Look For |
|-------|----------|
| Input validation | External inputs validated before use? |
| Injection | String concatenation in queries or commands? |
| Secrets | Hardcoded credentials, API keys, tokens? |
| Auth | Permission checks where needed? |

### Completeness Check

| Check | Look For |
|-------|----------|
| TODOs | Any TODO/FIXME/HACK left in the diff? |
| Debug code | Console.log, print statements, debugger? |
| Tests | Were tests added for new functionality? |
| Imports | All imports used? Any missing? |

### Quality Gates

Run the project's quality gate commands:
```bash
# Run and capture results (truncate output to first 20 lines if verbose)
[lint command]
[typecheck command]
[test command]
```

Record pass/fail. If tests fail, note WHICH tests and the first few lines of error output — do not dump the full test suite output.

## Step 3: Report

Write the report to a file, return a brief summary to the parent.

### Report File

Write to: `{docs.qaReports}/TASKQA-[TASK-ID].md`

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

**Result**: PASS | FAIL
**Date**: [date]

## Acceptance Criteria

| AC # | Criterion | Result | Notes |
|------|-----------|--------|-------|
| AC-1 | [criterion] | PASS / FAIL | [brief note] |
| AC-2 | [criterion] | PASS / FAIL | [brief note] |

## Quality Gates

| Gate | Result |
|------|--------|
| Lint | PASS / FAIL |
| Type Check | PASS / FAIL |
| Tests | PASS / FAIL |

## Findings

### [TQA-NNN] [Title] (if any findings)
**Severity**: Critical | High | Medium | Low
**File**: `path/to/file.ts:line`
**Issue**: [1-2 sentences]
**Recommendation**: [1 sentence]

## Summary
[PASS: Ready for final QA | FAIL: [N] findings need fixing before proceeding]
```

### Return to Parent

Return ONLY this to the parent session:

```
TASK-ID: [ID]
Result: PASS | FAIL
Findings: [N] Critical, [N] High, [N] Medium, [N] Low
Report: {docs.qaReports}/TASKQA-[TASK-ID].md
```

**Do not return the full report contents.** The parent only needs the summary.

## Batch Processing

When reviewing multiple tasks in one session:

- **Max 3 tasks per session** — after 3, checkpoint and suggest continuing in a new session
- Process one task at a time (read diff, check, write report, then move to next)
- Update TASK-INDEX.md after each task review

## Handling Failures

If a task fails Task QA:

1. Write the report with specific findings
2. Do NOT generate rework tasks (that's scorpio-qa-rework's job)
3. Report the failure to the parent
4. The parent can either:
   - Fix simple issues immediately and re-run Task QA
   - Continue to the next task and batch the fixes later

## What NOT To Do

- Do not read the entire codebase for context — read only the diff and task spec
- Do not do UI testing — that's scorpio-qa-final's job
- Do not do cross-task integration review — that's scorpio-qa-final's job
- Do not generate rework tasks — that's scorpio-qa-rework's job
- Do not dump full test suite output into the report — summarize
- Do not return the full report to the parent — write to file, return summary

## Skill Chain

Task QA sits between implementation and final-pass QA:

```
scorpio-execute (implement) → scorpio-qa (per-task review) → scorpio-qa-final (final pass) → scorpio-qa-rework
```