Escalate

Escalate

Generate a handoff prompt for another agent when you're stuck and need fresh perspective.

When to Use

• You've tried multiple approaches and keep hitting the same walls
• You're going in circles and want a fresh perspective
• You need to context-switch but want to preserve progress for Codex CLI or another agent

Workflow

/​escalate → Choose detail level → Choose handoff mode → Analyze session → Generate prompt → pbcopy

Step 1: Ask Detail Level

Use AskUserQuestion to ask:

How much context for the handoff?

1. Concise (~200-400 words) - Problem, key blockers, clear ask
2. Detailed (~500-800 words) - Above plus files, errors, code snippets

Step 2: Ask Handoff Mode

Use AskUserQuestion to ask:

What should the next agent do?

1. Continue - Pick up where I left off and solve this
2. Fresh perspective - Ignore my approaches, try something new
3. Validate first - Confirm my understanding, then propose alternatives
4. Other - [let user specify custom instruction]

Step 3: Analyze the Session

Review the conversation to extract:

For concise mode: Focus on Problem, Approaches Tried, and one key blocker.

For detailed mode: Include all sections with code snippets and full error messages.

Step 4: Generate the Prompt

Template

# Problem

[Clear statement of what you're trying to accomplish]

# Approaches Tried

- **Approach 1:** [what you tried]
  - Result: [what happened]
  - Why it failed: [analysis]

- **Approach 2:** [what you tried]
  - Result: [what happened]
  - Why it failed: [analysis]

[Continue for each significant approach]

# Current Hypothesis

[What you think might be the root cause or blocker]

# Relevant Context

**Files:**
- `path/​to/​file.ts` - [why it's relevant]
- `path/​to/​other.ts` - [why it's relevant]

**Errors:**

[Exact error messages]

**Constraints:**
- [Things that must be preserved]
- [Approaches to avoid and why]

# Your Task

[Based on handoff mode:]

- Continue: "Pick up where I left off. The context above shows what's been tried. Find a path forward and solve this."
- Fresh perspective: "Ignore the approaches above - they haven't worked. Look at this problem fresh and propose a different strategy."
- Validate first: "First, confirm whether my understanding of the problem is correct. Then propose an alternative approach."
- Other: [User's custom instruction]

Step 5: Copy to Clipboard

echo "[generated prompt]" | pbcopy

Use a heredoc for multi-line content:

pbcopy << 'EOF'
[generated prompt content]
EOF

Step 6: Confirm

Tell the user:

Handoff prompt copied to clipboard. Paste into Codex CLI to continue.

Quality Checklist

• Problem statement is clear and self-contained
• Approaches include WHY they failed, not just WHAT was tried
• Hypothesis is specific, not vague
• File paths are absolute or repo-relative
• Error messages are exact, not paraphrased
• Constraints call out landmines to avoid
• Handoff instruction matches selected mode

Common Mistakes

Example Output (Concise)

# Problem

Trying to get Jest tests to run in a WordPress plugin. Tests pass locally but fail in CI with "Cannot find module '@wordpress/​scripts'" errors.

# Approaches Tried

- **Verified node_modules:** Confirmed package is installed, same versions local and CI
- **Cleared CI cache:** Rebuilt from scratch, same error
- **Checked path resolution:** Added moduleNameMapper in jest.config.js, no change

# Current Hypothesis

CI environment might have different NODE_PATH or module resolution behavior. The @wordpress/​scripts package uses a nested dependency structure.

# Your Task

Pick up where I left off. The context above shows what's been tried. Find a path forward and solve this.