External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Adjusted documentation

Browse Source
This commit is contained in:
Renn F
2025-12-30 19:37:03 +01:00
parent d7e93ece25
commit eedf06d18a
12 changed files with 3056 additions and 482 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflows/ESCALATION.md
+218 -58
View File
@@ -1,23 +1,110 @@
# Escalation Guide
> **Status:** Implemented
>
> This document describes the task escalation system and CEO approval workflow.
---
## Escalation Chain
The escalation chain is strictly enforced - you cannot skip levels:
```
Developer/QA/Documenter
│
▼
Cell PM
Cell PM (be-pm, fe-pm, ux-pm)
│
▼
Main PM
Main PM (main-pm)
│
▼
Product Owner
Product Owner (product-owner)
│
▼
CEO
CEO (ceo)
```
### Detailed Chain
| Agent | Escalates To |
|-------|--------------|
| be-dev-1, be-dev-2 | be-pm |
| be-qa | be-pm |
| be-doc | be-pm |
| fe-dev-1, fe-dev-2 | fe-pm |
| fe-qa | fe-pm |
| fe-doc | fe-pm |
| ux-dev-1, ux-dev-2 | ux-pm |
| ux-qa | ux-pm |
| ux-doc | ux-pm |
| be-pm, fe-pm, ux-pm | main-pm |
| main-pm | product-owner |
| product-owner | ceo |
| head-marketing | ceo |
| auditor | ceo |
---
## Types of Escalation
### 1. Task Escalation (`roboco_task_escalate`)
Used when you need help with a specific task. Available to ALL agents.
```python
roboco_task_escalate(
task_id="uuid-here",
reason="Need clarification on API contract - acceptance criteria unclear"
)
```
**Key Points:**
- Auto-routes to your escalation target (you cannot specify a different target)
- Creates a high-priority notification requiring acknowledgment
- Task status remains unchanged (you can keep working if possible)
- Escalation is logged in task history
### 2. CEO Escalation (`roboco_task_escalate_to_ceo`)
PM-only. Used for major tasks requiring CEO sign-off:
```python
roboco_task_escalate_to_ceo(
task_id="uuid-here",
notes="Major feature ready for final review"
)
```
**Requirements:**
- Task must be in `awaiting_pm_review` status
- For git tasks, PR must exist (`pr_number` must be set)
- Only PMs (cell_pm, main_pm) can escalate to CEO
**Result:**
- Status changes to `awaiting_ceo_approval`
- CEO receives high-priority notification requiring ACK
### 3. Soft Block Escalation
When blocked by external factors (not another task):
```python
roboco_task_soft_block(
task_id="uuid-here",
reason="Waiting for production API credentials",
blocker_type="external_dependency",
what_needed="AWS credentials for production environment"
)
```
**Result:**
- Status changes to `blocked`
- PM receives notification with ACTION REQUIRED
- PM MUST call `roboco_task_unblock()` when resolved
- Verbal resolution in chat is NOT enough
---
## When to Escalate
@@ -25,46 +112,80 @@ Developer/QA/Documenter
| 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` |
| Blocked by external factor | Cell PM | `roboco_task_soft_block` |
| Blocked by another task | Cell PM | `roboco_task_block` + `roboco_task_escalate` |
| Cross-cell coordination needed | Cell PM (routes to 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) |
| Major feature ready for merge | CEO | `roboco_task_escalate_to_ceo` (PM only) |
---
## Escalation Tools
## CEO Approval Workflow
### For All Agents: `roboco_task_escalate`
For major tasks (parent tasks, high-priority features, breaking changes):
Escalate a task-related issue:
```
awaiting_pm_review
│
▼
PM reviews and decides to escalate
│
roboco_task_escalate_to_ceo(task_id, notes)
│
▼
awaiting_ceo_approval
│
┌────────────────┴────────────────┐
│ │
CEO APPROVES CEO REJECTS
│ │
roboco_task_ceo_approve() roboco_task_ceo_reject(notes)
│ │
▼ ▼
completed needs_revision
│
(assigned back to
original developer)
```
### CEO Approval Queue
PMs can view tasks awaiting CEO approval:
```python
roboco_task_escalate(
# Get all tasks awaiting CEO approval (org-wide)
roboco_tasks_awaiting_ceo()
```
### CEO Actions
```python
# Approve and complete
roboco_task_ceo_approve(task_id, notes="Approved. Great work!")
# Reject and send back for revision
roboco_task_ceo_reject(task_id, notes="Need to address X before merge")
```
---
## Force Completion (CEO Only)
When subtasks are cancelled but parent should complete:
```python
roboco_task_complete(
task_id="uuid-here",
reason="Need clarification on API contract - acceptance criteria unclear",
escalate_to="be-pm" # Optional - auto-routes if omitted
force_with_cancelled=True,
justification="Subtask TASK-123 cancelled - functionality no longer needed"
)
```
**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
)
```
**Requirements:**
- Only CEO can use `force_with_cancelled`
- Justification is required
- Does NOT work for pending/in_progress subtasks (only cancelled)
---
@@ -79,6 +200,7 @@ roboco_escalate(
| 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" |
| Low context | "Need more background on why this was designed this way" |
### QA Escalations
@@ -89,6 +211,14 @@ roboco_escalate(
| Blocking issue found | "Critical security flaw - should we halt?" |
| Test environment issue | "Staging is down, can't proceed" |
### Documenter Escalations
| Reason | Example |
|--------|---------|
| Missing context | "Developer journal doesn't explain design decisions" |
| Scope question | "Should I document internal APIs?" |
| Access needed | "Can't view the code changes" |
### Cell PM Escalations
| Reason | Example |
@@ -102,21 +232,24 @@ roboco_escalate(
## 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
1. **Escalation notification sent** to your escalation target
2. **Notification is high-priority** and requires acknowledgment
3. **Task status unchanged** (you can keep working if possible)
4. **Target MUST ACK** the notification
5. **Target investigates** and responds
6. **For blocks**: PM must call `roboco_task_unblock()` when resolved
---
## Escalation vs Block vs Pause
## Escalation vs Block vs Pause vs Substitute
| 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 |
| Action | When | Status Change | Tool |
|--------|------|---------------|------|
| **Escalate** | Need help/decision | No change | `roboco_task_escalate` |
| **Block (hard)** | Waiting on another task | → blocked | `roboco_task_block` |
| **Block (soft)** | Waiting on external factor | → blocked | `roboco_task_soft_block` |
| **Pause** | Need to stop temporarily | → paused | `roboco_task_pause` |
| **Substitute** | Can't continue, release task | → pending/awaiting_pm_review | `roboco_task_substitute` |
### Combining Actions
@@ -124,12 +257,42 @@ 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")
roboco_task_soft_block(
task_id,
"Waiting for API access",
"external_dependency",
"Need production API keys from DevOps"
)
# PM will be notified automatically
```
---
## Substitution (Graceful Exit)
When you can't continue a task:
```python
roboco_task_substitute(
task_id="uuid-here",
reason="low_context",
details="Need more background on the authentication system design"
)
```
### Substitution Reasons
| Reason | Result Status | Use When |
|--------|---------------|----------|
| `task_complete` | awaiting_qa | Finished work, releasing for review |
| `low_context` | pending | Insufficient context to continue |
| `out_of_scope_team` | pending | Task belongs to different team |
| `out_of_scope_role` | pending | Task requires different role |
| `max_retries` | pending | Exceeded retry limit |
| `blocked_external` | blocked | Need skills outside your capabilities |
---
## Good Escalation Format
```python
@@ -164,21 +327,18 @@ When you receive an escalation:
4. **Communicate** - Message the agent with decision
5. **Unblock if needed** - `roboco_task_unblock(task_id)`
**CRITICAL**: For soft blocks, verbal resolution is NOT enough. You MUST call:
```python
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
- **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 (can't skip Cell PM)
- **Don't escalate resolved issues** - Only escalate if you actually need help
- **Don't bypass the chain** - The `escalate_to` parameter is validated against your escalation target