troubleshooting-execute

Troubleshooting Execute Command

Overview

Reference guide for diagnosing and recovering from execute command failures.

This skill provides recovery strategies for common execute command errors. Use it when execution fails or produces unexpected results.

When to Use

Use this skill when:

• Phase execution fails (sequential or parallel)
• Parallel agent fails or doesn't complete
• Merge conflicts occur during stacking
• Worktree creation fails
• Main worktree not found
• Need to resume execution after fixing an issue

This is a reference skill - consult when errors occur, not part of normal execution flow.

Error Categories

1. Sequential Phase Execution Failure

Symptoms:

• Task agent fails mid-execution
• Quality checks fail (test, lint, build)
• Branch not created after task completes

Error message format:

❌ Phase {id} Execution Failed

**Task**: {task-id}
**Error**: {error-message}

Resolution steps:

1. Review the error output - Understand what failed (test? build? implementation?)

2. Check current state:

   cd .worktrees/{runid}-main
   git status
   git log --oneline -5
   

3. Fix manually if needed:

   # Current branch already has completed work from previous tasks
   # Fix the issue in the working directory
   
   # Run quality checks
   bash <<'EOF'
   npm test
   if [ $? -ne 0 ]; then
     echo "❌ Tests failed"
     exit 1
   fi
   
   npm run lint
   if [ $? -ne 0 ]; then
     echo "❌ Lint failed"
     exit 1
   fi
   
   npm run build
   if [ $? -ne 0 ]; then
     echo "❌ Build failed"
     exit 1
   fi
   EOF
   
   # Create branch if task completed but branch wasn't created
   gs branch create {runid}-task-{phase}-{task}-{name} -m "[Task {phase}.{task}] {description}"
   

4. Resume execution:

   • If fixed manually: Continue to next task
   • If need fresh attempt: Reset branch and re-run task
   • If plan was wrong: Update plan and re-execute from this phase

2. Parallel Phase - Agent Failure