roboco/docs/rag/troubleshooting/common-issues.md

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:

1. Missing required fields
2. Waiting on parallel action
3. Invalid transition attempted

Check:

• Branch exists?
• For awaiting_pm_review: both docs_complete AND pr_created?
• Is transition valid from current status?

Notification Not Received

Problem: Expected notification didn't arrive

Causes:

1. Sender doesn't have notification permission
2. Notification filtering
3. 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_context field 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) or roboco_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:

1. Is the recipient in your own cell? Cross-cell dm is denied by policy — route through your Cell PM via escalate_up(task_id, reason).
2. 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.
3. 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.