roboco/docs/workflows/ESCALATION.md

Escalation Guide

Escalation Chain

Developer/QA/Documenter
         │
         ▼
      Cell PM
         │
         ▼
      Main PM
         │
         ▼
   Product Owner
         │
         ▼
        CEO

---

When to Escalate

Situation	Escalate To	Tool
Need PM decision	Cell PM	roboco_task_escalate
Blocked by external factor	Cell PM	roboco_task_escalate
Cross-cell coordination needed	Cell PM → Main PM	roboco_task_escalate
Scope creep beyond task	Cell PM	roboco_task_escalate
Resource/priority conflict	Cell PM	roboco_task_escalate
Cell PM unresponsive	Main PM	roboco_task_escalate
Company-wide issue	Product Owner	roboco_escalate (PM only)

---

Escalation Tools

For All Agents: roboco_task_escalate

Escalate a task-related issue:

roboco_task_escalate(
    task_id="uuid-here",
    reason="Need clarification on API contract - acceptance criteria unclear",
    escalate_to="be-pm"         # Optional - auto-routes if omitted
)

Auto-routing (when escalate_to omitted):

• Developer/QA/Doc → Cell PM
• Cell PM → Main PM
• Main PM → Product Owner

For PM/Board Only: roboco_escalate

General escalation (not task-specific):

roboco_escalate(
    escalate_to="main-pm",
    subject="Need cross-cell coordination",
    description="Backend and frontend teams need to sync on API changes",
    task_id="uuid-optional"     # Optional link
)

---

Escalation Reasons by Role

Developer Escalations

Reason	Example
Unclear requirements	"Acceptance criteria doesn't specify error handling"
Blocked by other task	"Waiting on auth service from fe-dev-1"
Scope question	"Should I also handle edge case X?"
Need decision	"Two valid approaches - need PM guidance"
Technical blocker	"Can't reproduce bug in dev environment"

QA Escalations

Reason	Example
Can't reproduce	"Bug not reproducible with given steps"
Unclear test criteria	"Don't know what 'acceptable performance' means"
Blocking issue found	"Critical security flaw - should we halt?"
Test environment issue	"Staging is down, can't proceed"

Cell PM Escalations

Reason	Example
Cross-cell dependency	"Need frontend to expose new endpoint"
Resource conflict	"Both tasks need be-dev-1, can't parallelize"
Priority question	"Two P1 tasks - which first?"
Scope change	"Requirements changed mid-sprint"

---

What Happens When You Escalate

1. Escalation notification sent to target
2. Task status unchanged (you can keep working if possible)
3. Escalation logged in task history
4. Target must ACK the escalation
5. Resolution tracked when target responds

---

Escalation vs Block vs Pause

Action	When	Effect
Escalate	Need help/decision	Notifies PM, you can continue
Block	Waiting on another task	Status → blocked, can claim other work
Pause	Need to stop temporarily	Status → paused, state saved

Combining Actions

Often you'll combine:

# Blocked AND need PM help
roboco_task_block(task_id, blocker_task_id)
roboco_task_escalate(task_id, "Blocked on auth service, need PM to coordinate")

---

Good Escalation Format

roboco_task_escalate(
    task_id="uuid-here",
    reason="""
ISSUE: API contract unclear
CONTEXT: Implementing user endpoint, acceptance criteria says "return user data"
QUESTION: Should I include sensitive fields (email, phone)? What about nested relations?
ATTEMPTED: Checked existing endpoints, no consistent pattern
BLOCKING: Can't proceed without this decision
"""
)

Include:

• What's the issue
• What context you have
• Specific question
• What you already tried
• How it's affecting work

---

Responding to Escalations (PM)

When you receive an escalation:

1. ACK immediately - roboco_notify_ack(notification_id)
2. Investigate - Read task, journals, messages
3. Decide - Make the call or escalate further
4. Communicate - Message the agent with decision
5. Unblock if needed - roboco_task_unblock(task_id)

---

Escalation Anti-Patterns

❌ Don't escalate without trying first

• Check documentation, journals, similar tasks

❌ Don't escalate vague issues

• "I'm stuck" → Instead: "Stuck on X because Y, tried Z"

❌ Don't escalate too late

• Escalate when you recognize you're blocked, not after hours of spinning

❌ Don't skip levels

• Developer → Cell PM → Main PM (don't skip Cell PM)

❌ Don't escalate resolved issues

• Only escalate if you actually need help