879afc14a4
* fix(board): LEARN decisions name the item, not its per-cycle index A cycle's reject reasons are rendered into the NEXT cycle's exploration prompt, but the ref recorded alongside each reason was the item's stored id (item-0/item-1) — a per-cycle index that means something different every cycle and appears nowhere the explorer can resolve. The reason survived the loop; what it was about did not. Record the item's title instead, via a shared learn_ref() helper (falls back to the id when title-less, and reads target_task_title for Scales, whose items name the live task they mutate). * chore(lint): satisfy ruff 0.16 — keyword-only signatures and markdown formatting The dev toolchain resolved ruff 0.16.0, which stabilises PLR0917 (too many positional arguments) and formats python code blocks inside markdown. Both fired repo-wide and neither had anything to do with the code they flagged. - 36 signatures gain a `*` so their tail arguments are keyword-only, and the 104 call sites that passed them positionally are converted. mypy was the safety net for the static ones; the full suite caught nine more that only bind at runtime (the MCP tool functions, whose real callers already pass named JSON arguments). - 28 markdown files reformatted by 0.16's code-block formatter. - One RUF036 (`None` mid-union) autofixed in the GitLab provider. * fix(gateway): log the reason when a verb rejects A rejected envelope rides an HTTP 200, its body is never logged, and there is no trace table — so in the access log a verb an agent could not satisfy looks identical to one that worked. On 2026-07-25 four Board Programs (Periscope, Sentinel, Scales, Barfly) each POSTed their propose verb three or four times, persisted nothing, and left their exploration tasks PENDING; the reason was unrecoverable afterwards, from the logs or from the agents' own transcripts. Log error/message/remediate/missing plus the calling agent at envelope_to_response — the one chokepoint every v1 flow and do route returns through. Success envelopes stay silent. --------- Co-authored-by: Renn F <rennf93@users.noreply.github.com>
3.9 KiB
Common Issues
Permission Denied
Error: "Not authorized for this action"
Cause: Your role doesn't have permission
Check Permissions:
| Action | Allowed Roles |
|---|---|
| Create / delegate task | PM only (Cell PM, Main PM) |
| Cancel task | PM, CEO |
| Pass/fail QA | QA only |
| Complete docs | Documenter only |
| Complete task | PM only |
Send notification (notify) |
PM, Board |
Solution: Request appropriate role to perform action
Task Stuck in Status
Problem: Task won't transition
Causes:
- Missing required fields
- Waiting on parallel action
- Invalid transition attempted
Check:
- Branch exists?
- For
awaiting_pm_review: bothdocs_completeANDpr_created? - Is transition valid from current status?
Notification Not Received
Problem: Expected notification didn't arrive
Causes:
- Sender doesn't have notification permission
- Notification filtering
- Already acknowledged
Solutions:
- Check
notify_list()for all notifications - Verify sender has PM/Board role
- Check if already acknowledged via
notify_get(notification_id)
Escalation Not Routing
Problem: Escalation went to wrong person
Cause: escalate_up auto-routes to your escalation target
Chain:
Cell members → Cell PM → Main PM → Product Owner → CEO
Cannot skip levels or choose target. (Only Main PM / Board call escalate_to_ceo; cell members and Cell PMs use escalate_up.)
Tests Failing Before Submit
Problem: Tests fail, can't submit to QA
Checklist:
# Backend
uv run pytest # Tests
uv run ruff check . # Linting
uv run mypy roboco/ # Type check
# Frontend
pnpm test
pnpm lint
pnpm typecheck
Fix all issues before submitting.
Lost Context After Pause
Problem: Resuming task, forgot context
Solutions:
- Read
quick_contextfield on task - Read your journal for this task
- Get proactive context:
roboco_get_proactive_context(task_id)
Documentation Path Confusion
Problem: Unsure where to write documentation
Solution: Use roboco_docs_write() - system handles paths automatically
roboco_docs_write(
{
"task_id": "your-task-uuid",
"filename": "feature.md",
"doc_type": "api", # api, qa, guide, readme, changelog, architecture, design
"title": "Feature Documentation",
"content": "...",
}
)
- Team folder: Determined from your agent ID
- Subfolder: Determined by doc_type
- No path decisions needed
Documentation Already Exists
Problem: Want to update existing doc but created duplicate
Cause: Content was too different from existing doc (RAG similarity < 0.75)
Solution:
- Ensure content covers the same topic
- Or delete duplicate:
roboco_docs_delete(path) - Check existing:
roboco_docs_list(task_id)orroboco_kb_search("topic")
Note: roboco_docs_write() auto-deduplicates via RAG by content similarity. If content is semantically similar (~75%+), it updates instead of creating new.
A2A Message Not Delivered
Problem: Sent a dm but no response
Check:
- Is the recipient in your own cell? Cross-cell
dmis denied by policy — route through your Cell PM viaescalate_up(task_id, reason). - Use the right slug — recipient slugs come from your known team/cell roster (see
docs/rag/architecture/org-structure.md's Cells table), not a runtime discovery call. - Did you include
task_id? It anchors the message to the work.
Solutions:
- Same-cell peer:
dm(recipient="be-qa", text="...", task_id="...") - Anything cross-cell or needing PM action:
escalate_up(task_id, reason)
Cross-Cell Message Denied
Error: A dm to an agent outside your cell is rejected by policy
Cause: Direct A2A is same-cell only — there is no cross-cell dm
Solution: Escalate up the chain. Use escalate_up(task_id, reason) so your Cell PM can coordinate with the other cell's PM.