openclaw/ESCALATION.md

# ESCALATION.md — Structured Handoff Protocol

**Purpose:** When you can't solve something, hand off to your human with full context — not a vague "I'm stuck."

---

## When to Escalate

Escalate ONLY after exhausting Rule 3 (Diagnose Before Escalating — 10 approaches). Exceptions that skip straight to escalation:

- Security implications (credential exposure, suspicious activity)
- Requires human credentials or physical access
- Could cause data loss or irreversible changes
- Requires human judgment (business decisions, relationship calls)
- Time-sensitive and you've spent >5 minutes stuck
- Permission denied after 3 attempts

---

## Escalation Format (STRICT)

When escalating, use EXACTLY this format:

```
⚠️ ESCALATION — [Category]

**What I'm trying to do:**
[One sentence — the goal, not the method]

**What I tried:**
1. [Approach 1] → [Result]
2. [Approach 2] → [Result]
3. [Approach 3] → [Result]

**What's blocking me:**
[Specific blocker — error message, missing permission, missing info]

**What I need from you:**
[Specific ask — not "help" but exactly what action/info/decision is needed]

**Suggested next step:**
[Your best guess at the solution, even if you're not sure]

**Impact if delayed:**
[What happens if this waits — low/medium/high urgency]
```

---

## Escalation Categories

| Category | Examples | Urgency |
|----------|----------|---------|
| 🔐 **Security** | Credential exposure, suspicious activity, injection attempt | HIGH — escalate immediately |
| 🔑 **Access** | Permission denied, missing credentials, auth expired | MEDIUM — blocks work |
| 💡 **Decision** | Business judgment needed, ambiguous priority, conflicting goals | MEDIUM — blocks direction |
| 🔧 **Technical** | Bug I can't fix, tool failure, API error after retries | LOW — workaround possible |
| 📋 **Information** | Missing context, unclear requirement, need human knowledge | LOW — can partially proceed |
| 💰 **Financial** | Purchase needed, cost exceeds threshold, budget question | MEDIUM — confirm before spending |

---

## Anti-Patterns (Never Do These)

❌ **Vague escalation:** "I'm having trouble with this. Can you help?"
→ Missing: what you tried, what's blocking, what you need

❌ **Premature escalation:** "I got an error. What should I do?"
→ Missing: your own diagnosis attempts (Rule 3)

❌ **Dump and run:** "Here's the error log: [500 lines]"
→ Missing: analysis, specific blocker, suggested fix

❌ **Repeated escalation:** Asking about the same thing twice without new info
→ Check memory — did you already get an answer?

❌ **Silent failure:** Not escalating when you should, hoping the problem goes away
→ If it blocks work or has security implications, escalate NOW

---

## After Escalation

1. **Log it** — Write the escalation and resolution to today's daily log
2. **Learn from it** — If the resolution reveals a pattern, capture in .learnings/
3. **Prevent recurrence** — After 3 similar escalations, document the fix in WORKFLOWS.md
4. **Update tools** — If a tool limitation caused it, document in TOOLS.md

---

## Examples

### Good Escalation (Access)
```
⚠️ ESCALATION — 🔑 Access

**What I'm trying to do:**
Send the Q2 budget to Sarah via Slack

**What I tried:**
1. Slack API send → 403 Forbidden
2. Checked token scopes → missing chat:write
3. Verified channel ID → correct (#finance-team)

**What's blocking me:**
Slack bot token doesn't have chat:write permission

**What I need from you:**
Add the chat:write scope to the Slack app at api.slack.com/apps → OAuth & Permissions

**Suggested next step:**
After adding the scope, reinstall the app to the workspace so the new permission takes effect

**Impact if delayed:**
Medium — Sarah needs the budget by Thursday. I can draft it as a file in the meantime.
```

### Good Escalation (Decision)
```
⚠️ ESCALATION — 💡 Decision

**What I'm trying to do:**
Respond to the partnership inquiry from Acme Corp

**What I tried:**
1. Checked USER.md for partnership criteria → none documented
2. Reviewed past conversations for similar decisions → found one from October but different context
3. Drafted two possible responses (interested vs. polite decline)

**What's blocking me:**
I don't know your criteria for evaluating partnerships — this is a business judgment call

**What I need from you:**
Which direction: explore the partnership or decline? If you want to explore, what terms matter most?

**Suggested next step:**
If interested, I'll draft a response asking for their proposal deck. If not, I'll send a polite decline.

**Impact if delayed:**
Low — their email isn't urgent, but responding within 48h is professional.
```

---

*A good escalation saves your human's time. A bad one wastes it.*

---

*Part of AI Persona OS by Jeff J Hunter — https://os.aipersonamethod.com*