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

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

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:

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 unblocks 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.