Error Handling Skill

Use these patterns for consistent error handling across all agents.

Common Errors Table

Every agent should handle these common errors:

Error	Recovery
Uncommitted changes	Stash, commit, or abort
File already exists	Ask user: overwrite or abort
Branch doesn't exist	List available branches
Tests fail	Fix before proceeding
MCP tool unavailable	Check prerequisites, provide installation instructions
Sub-agent timeout	Retry or escalate to user

Cleanup on Failure Protocol

When a workflow fails, perform cleanup:

1. Check for stashed changes: git stash list
2. Restore stash if needed: git stash pop
3. Return to original branch: git checkout {ORIGINAL_BRANCH}
4. Report partial progress to user

Cross-Agent Error Recovery

When a sub-agent fails, follow this sequence:

1. CAPTURE: Record error details
   - Agent name and task
   - Error message and type
   - Partial progress (files created, etc.)

2. STABILIZE: Restore safe state
   - Spawn git-operator: restore-workflow
   - Pop any stashes created
   - Return to original branch

3. CHECKPOINT: Present options to user
   - R) Retry - Attempt the operation again
   - S) Skip  - Continue without this step
   - A) Abort - Stop workflow, save state
   - D) Debug - Spawn debug-analyst

4. RECORD: Update workflow state
   - Mark task status in 00-index.md
   - Log error for post-mortem
   - Continue or exit based on user choice

Agent Spawning Depth Limit

To prevent infinite recursion:

• Maximum depth: 5 levels (configurable per workflow)
• Include depth in spawn prompt: [DEPTH: 3/5]

Depth tracking rules:

Caller	Sub-Agent	Depth Change
Main session	Orchestrator	0 → 1
Orchestrator	Specialist	+1
Orchestrator	Worker	+1
Specialist	Worker	+1
Worker	Worker	+1

At max depth:

1. REFUSE to spawn further sub-agents
2. REPORT depth limit reached
3. ESCALATE to user with checkpoint

Cycle Detection

Detect and prevent agent cycles:

If agent_name in spawning_chain:
    ABORT with "Cycle detected: {chain} → {agent_name}"

Example cycle: pr-review-manager → task-implementer → pr-review-manager