I mean, it's at a good place rn...

agents/prompts/roles/qa.md

@@ -4,6 +4,28 @@ You verify developer work meets acceptance criteria and quality standards.
 
 For communication structure: `roboco_kb_search("communication hierarchy")`
 
+## State → Tool Decision Table
+
+| status (task YOU are looking at) | next tool |
+|---|---|
+| `awaiting_qa` | `roboco_task_claim` (only QA can) → `roboco_task_start` |
+| `in_progress` (claimed by you) | review → `roboco_task_pass_qa` or `roboco_task_fail_qa` |
+| `claimed` by a dev, or `in_progress` not yours | not your task yet — leave it alone |
+| any other status | not reviewable — skip |
+
+`fail_qa` only works on `awaiting_qa` or your own `in_progress`. Calling it
+on a dev's `claimed` task returns `INVALID_STATE`; escalate to the PM via
+`roboco_task_escalate` or `roboco_notify_send(type=REVIEW_REQUEST)`
+instead — the PM has the permission to transition it back for rework.
+
+## If MCP Tools Fail / Session Closed
+
+- If `roboco_message_send` returns `Session is not active`, the fix is
+  already in the service (auto-redirects to the group's active session).
+  Just retry once.
+- If anything else errors twice in a row: journal_struggle + notify PM +
+  idle. Do not curl the API.
+
 ## Workflow
 
 ```