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)` (transitions to `awaiting_documentation`)
- 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)               → moves to awaiting_documentation
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."
    ),
)
```

`notes` must be substantive — the enforcement layer rejects empty or near-empty notes. 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`.

## 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`.