Execution Recovery

Apex2's execution optimization suite implemented as a Claude Code skill. Provides robust recovery from common execution failures.

Instructions

When invoked (automatically on errors or explicitly when help is needed), diagnose and fix execution problems:

1. Immediate Error Triage

Quickly categorize the error type to apply the right recovery strategy:

Syntax Errors:

• Python: SyntaxError, IndentationError, NameError
• JavaScript: SyntaxError, ReferenceError
• Shell: syntax error near token, unexpected operator

Import/Module Errors:

• ModuleNotFoundError, ImportError (Python)
• Cannot find module (Node.js)
• dependency resolution failures

Path/File Issues:

• No such file or directory
• Permission denied
• File already exists
• Directory not empty

Network/Connection Problems:

• Connection refused, timeout
• DNS resolution failures
• Authentication failures
• Rate limiting

2. Recovery Strategies by Error Type

Syntax Error Recovery

1. Diagnose the specific line:

   # Python syntax checking
   python -m py_compile filename.py
   # or specific line diagnosis
   python -c "import ast; ast.parse(open('filename.py').read())"
   
   # JavaScript syntax checking  
   node -c filename.js
   npm install eslint --save-dev && npx eslint filename.js
   

2. Common fixes to apply:

   • Fix missing parenthesis, brackets, quotes
   • Correct indentation (Python-specific)
   • Add missing semicolons (JS-specific)
   • Escape special characters in strings
   • Fix function call syntax

3. Heredoc Management (for shell scripts):

   # Validate heredoc syntax
   cat << 'EOF' > script.sh
   # script content here
   EOF
   

Import/Dependency Recovery

1. Diagnose missing dependencies:

   # Python imports
   python -c "import missing_module" 2>&1 | grep ModuleNotFoundError
   
   # Node.js
   npm ls missing-package
   

2. Install solutions:

   # Python
   pip install missing-package
   # Add to requirements.txt
   
   # Node.js
   npm install missing-package
   # Add to package.json dependencies
   

3. Version conflicts:

   # Check versions
   pip show package-name
   npm list package-name
   
   # Install specific version
   pip install package==version
   npm install package@version
   

Path/File Recovery

1. Path validation:

   # Check if file exists
   ls -la file-path
   dirname file-path && ls -la $(dirname file-path)
   
   # Current working directory
   pwd
   
   # Relative vs absolute path testing
   echo $(pwd)/relative-path
   

2. Permission fixes:

   # Make executable
   chmod +x script.sh
   
   # Read/write permissions
   chmod 644 file.txt
   chmod 755 directory/
   

3. Directory creation:

   # Create parents as needed
   mkdir -p path/to/directory
   
   # Safe file creation
   touch new-file.txt
   

Network/Connection Recovery

1. Connectivity testing:

   # Test basic connectivity
   ping -c 3 example.com
   curl -I https://example.com
   
   # Check specific ports
   telnet host port
   nc -zv host port
   

2. DNS resolution:

   # Check DNS
   nslookup hostname
   dig hostname
   
   # Test different DNS servers
   nslookup hostname 8.8.8.8
   

3. Authentication and retries:

   # Retry with exponential backoff
   # Use auth tokens appropriately
   # Check rate limits and wait periods
   

3. Advanced Recovery Techniques

Heredoc Repair (for shell scripts)

# Fix indentation in heredoc
cat << 'EOF' > fixed-script.sh
#!/bin/bash
echo "Fix indentation issues"
# Other commands
EOF

Session Recovery

# Detect stuck tmux/session issues
tmux list-sessions
tmux kill-session -t session-name

# Start fresh session
tmux new-session -d -s work-session

Long-Running Task Management

# Resume interrupted tasks
# Check progress of long operations
# Implement timeouts for very long commands
timeout 300s command-that-might-hang

4. Systematic Debugging Process

1. Capture the exact error message
2. Reproduce the error to isolate cause
3. Check recent changes that might have broken things
4. Apply the appropriate recovery strategy
5. Verify the fix works before proceeding

5. Prevention Strategies

Add safeguards to prevent recurrence:

• Input validation in scripts
• Error handling that catches common failures
• Automated testing before deployment
• Configuration validation on startup

Error Categories and Fixes

Docker/Microservice Issues

# Container not found
docker ps -a
docker logs container-name

# Port conflicts
netstat -tulpn | grep port-number
docker run -p different-port:port

Database Connection Problems

# Connection testing
psql -h host -U user -d database -c "SELECT 1;"
mysql -h host -u user -e "SELECT 1;"

# Service status
systemctl status postgresql
systemctl status mysql

Git Repository Issues

# Permission denied
git config --global core.sharedRepository group

# Corrupted repository
git fsck
git gc --prune=now

Output Format

Provide structured recovery report:

Error Analysis:
  Type: [syntax/import/path/network/other]
  Severity: [low/medium/high]
  Criticality: [blocking/warning/info]

Root Cause:
  Immediate cause: [what happened]
  Underlying issue: [why it happened]
  Contributing factors: [other factors]

Recovery Applied:
  Step 1: [action taken]
  Result: [success/failure]
  Step 2: [next action if needed]
  Result: [success/failure]

Solution Details:
  Code fixed: [show corrected code]
  Command executed: [show command]
  Changes made: [describe modifications]

Verification:
  Test performed: [how fix was verified]
  Result: [successful/unsuccessful]
  Additional steps: [if needed]

Prevention:
  Future safeguards: [how to prevent recurrence]
  Monitoring: [what to watch]
  Documentation: [what to update]

When to Use

This recovery skill is designed for:

• Automatic recovery when execution commands fail
• Manual intervention when complex errors occur
• Debugging mysterious failures
• Learning from mistakes to prevent recurrence
• Building robust execution pipelines

The goal is to turn execution failures into learning opportunities, with the system becoming more reliable through each recovery.