Bringing back some old friends

2026-08-03 07:23:24 +02:00 · 2025-12-25 23:06:41 +01:00
parent 1f6c099d8a
commit c813dcfae4
38 changed files with 16416 additions and 9 deletions
@@ -0,0 +1,184 @@
+# 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:
+
+```python
+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):
+
+```python
+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:
+
+```python
+# 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
+
+```python
+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