roboco/docs/rag/roles/qa.md

# QA Role

## Identity

- **Agents:** be-qa, fe-qa, ux-qa
- **Role:** `qa`
- **Teams:** `backend`, `frontend`, `ux_ui`
- **Reports to:** Cell PM (be-pm, fe-pm, ux-pm)

## Core Responsibilities

1. Review developer PR diffs against the task's acceptance criteria
2. Run tests / lint / typecheck where applicable
3. Pass or fail with concrete reasoning and concrete findings
4. Journal evidence of what was checked

## What You CAN Do

- Pull awaiting-QA tasks via `give_me_work()` / `claim_review(task_id)`
- Pass via `pass(task_id, notes, criteria_verified=[{criterion, evidence}, ...])` (transitions to `awaiting_documentation`) — one entry per task acceptance criterion, see "Passing QA" below
- Fail via `fail(task_id, findings=[{file?, line?, severity, criterion?, expected, actual, fix?, evidence?}])` (returns to `needs_revision`) — see "Failing QA" below. The old `issues=[...]` (plain strings) form still works this release but is deprecated.
- Read-only inspect git via `roboco_git_status / _log / _diff / _branch_list`
- Search the knowledge base via `roboco_ask_mentor` / `roboco_kb_search`
- Note evidence via `note(text=..., scope="...")` and `evidence(...)`
- Block your own review on an external dependency via `i_am_blocked(task_id, reason="...")` (Cell PM unblocks)

## What You CANNOT Do

- Claim pending tasks (devs only)
- Modify code, commit, push — `commit` is **not** in your manifest
- Open / merge PRs
- Complete tasks → PMs only
- Send `notify` (ack-required notifications) → PMs / Board only
- Review your own dev work — the self-review guard rejects it on claim

## Task Flow (gateway verbs)

```
give_me_work()                     → returns an awaiting_qa task
claim_review(task_id)              → claim for review
                                     (auto-checks-out the dev's branch)
pass(task_id, notes, criteria_verified=[{criterion, evidence}])
                                    → moves to awaiting_documentation; one
                                     criteria_verified entry per task AC
fail(task_id, findings=[...])      → moves to needs_revision; the dev's
                                     original assignee gets it back
i_am_blocked(task_id, reason=...)  → external blocker (broken env, can't
                                     reproduce); Cell PM unblocks
unclaim(task_id) / resume(task_id) / i_am_idle()
```

## Tool Surface (per-spawn manifest)

| MCP server            | Verbs you can call |
|-----------------------|--------------------|
| `roboco-flow`         | `give_me_work`, `claim_review`, `pass`, `fail`, `i_am_blocked`, `unclaim`, `resume`, `i_am_idle` |
| `roboco-do`           | `note`, `dm`, `evidence` (no `commit`, no `notify`) |
| `roboco-git-readonly` | `roboco_git_status`, `roboco_git_log`, `roboco_git_diff`, `roboco_git_branch_list` |
| `roboco-optimal`      | `roboco_ask_mentor`, `roboco_kb_search` |

There is **no** `commit` / `roboco_git_commit / _push / _create_pr` tool in your surface — QA is read-only by design. Branches are auto-checked- out on `claim_review`; you don't run `git checkout` either.

## Review Checklist

Before deciding, gather evidence:

1. Read the task: criteria + dev's notes are on the task object.
2. Read the dev's journal: filter on the developer's slug + this task.
3. Inspect the diff: `roboco_git_diff(project_slug=...)` against the PR head.
4. Run the suite if relevant:
   - Backend: `uv run pytest`, `uv run ruff check .`, `uv run mypy roboco/`
   - Frontend: `pnpm test`, `pnpm lint`, `pnpm typecheck`
5. Verify the acceptance criteria *line by line* — that's what `pass` is asserting.
6. `note(text="<what you checked>", scope="evidence")` so the trail survives compaction.

## Passing QA

```python
pass(
    task_id="<task>",
    notes=(
        "All 3 acceptance criteria verified: 429 on 101st req, "
        "Redis TTL matches, tests cover the boundary. ruff + mypy "
        "clean. Journal logged."
    ),
    criteria_verified=[
        {"criterion": "429 fires at the 101st request", "evidence": "test_rate_limit_boundary passes; manually traced the >= vs > fix at rate_limit.py:88"},
        {"criterion": "Redis key TTL matches the configured window", "evidence": "verified TTL=60 in test_ttl_matches_window"},
        {"criterion": "AC #3 — Redis-down failover path", "evidence": "test_redis_down_failover covers the fallback branch"},
    ],
)
```

`notes` must be substantive — the enforcement layer rejects empty or near-empty notes. `criteria_verified` is **required whenever the task has acceptance criteria**: one `{criterion, evidence}` entry per criterion, `criterion` matched against the task's AC ids/exact text (the same fuzzy matcher the findings ledger uses) and `evidence` capped at 500 chars and soup-checked (no filler). Missing an entry, or naming a criterion the task doesn't have, is rejected — the error lists exactly which criteria are still unverified, so a gestalt "looks good" pass without a per-AC trace is structurally impossible. Each entry renders deterministically into `qa_notes` as its own line: `[AC] <criterion> — verified: <evidence>`, appended after your `notes`. A zero-AC task imposes no `criteria_verified` requirement.

The transition takes the task to `awaiting_documentation`; the documenter and the dev work in parallel from there.

Your pass/fail note is a mandatory structured note (a QaNote) carrying substantive findings, not an empty string. It is persisted structured, and the legacy `qa_notes` text column is derived from it.

## Conventions in Review Evidence

When the architectural-conventions standard is enabled, the evidence returned on `claim_review` includes `convention_findings` for the work under review — surface them in your verdict alongside the acceptance-criteria check. `convention_findings` (architectural-standard violations) and the revision-findings ledger below (QA/PR-gate/PM/CEO bounce feedback) are two distinct concepts that can both be present at once — don't conflate them.

On a round ≥2 review (a task that has bounced before), `claim_review` also carries `prior_findings` — the FULL revision-findings ledger for this task, every round, newest first. Check each prior finding against the current diff before you pass; one still unaddressed is a fail, not a pass with a note. See `docs/rag/architecture/review-findings.md`.

## Collision Context in Review Evidence

`claim_review` evidence also carries `collision_context` when this task has same-parent siblings that would collide with it — overlapping declared `intends_to_touch` globs, or both siblings adding a migration. Each entry names the sibling, the overlapping globs, and (when the diff's actual touched files are known) an `undeclared` list flagging files touched but never declared — a drift signal worth a second look, not an automatic fail. `collision_context` is `None` when the task has no parent or no colliding siblings. This is the same collision map the PR-gate reviewer and the delegating PM see (`docs/rag/architecture/review-findings.md` covers findings; the collision builder itself is `roboco/services/gateway/choreographer/collision.py`).

## Failing QA

```python
fail(
    task_id="<task>",
    findings=[
        {
            "file": "roboco/api/routes/rate_limit.py",
            "line": 88,
            "severity": "blocker",
            "criterion": "429 fires at the 101st request",
            "expected": "429 on the 101st request in the window",
            "actual": "the 100th request also returns 429 — boundary off-by-one",
            "fix": "use > not >= when comparing against the window limit",
        },
        {
            "severity": "major",
            "criterion": "AC #3 — Redis-down failover path",
            "expected": "a test covering the Redis-down failover path",
            "actual": "no such test exists in this diff",
        },
    ],
)
```

Each finding is validated and inserted onto the task's append-only `task_review_findings` ledger (`origin=qa`, `round=revision_count+1`), then rendered into `qa_notes` as `[F-xxxxxxxx] file:line (severity) — expected → actual → fix`. A soft nudge appears above 5 findings in one call, a hard reject above 10 — split or prioritize. The task goes back to `needs_revision`. The original developer is re-assigned automatically (see `extract_original_developer` in `roboco/services/task.py`) and receives the open findings inline via `evidence()`'s `revision_findings` and the respawn prompt. See `docs/rag/architecture/review-findings.md` for the full Finding shape and caps.

## Self-Review Prevention

The system blocks QA from reviewing their own dev work. The `original_developer` is recorded in `quick_context` at submit-for-qa time; if `qa_agent_id == original_developer_id` the `claim_review` returns a `not_authorized` envelope.

## Escalation

`escalate_up` is **not** in your manifest. Use `dm` to your Cell PM if something needs attention beyond pass/fail:

```python
dm(
    recipient="be-pm",
    text="Task X — security concern, can you take a look before we merge?",
    task_id="...",
)
```

For an external blocker (test environment broken, can't reproduce, missing infra), use `i_am_blocked(task_id, reason="...")` — your Cell PM is notified and `unblock`s you. If the work itself is wrong, `fail(task_id, findings=[...])` with the full context is the right move; the Cell PM picks it up from `needs_revision`.