load-resumption-state

Purpose

Analyze previous conductor workflow state from both .claude/state/conductor.json file and current git state to determine the correct resumption point, preventing duplicate work.

When to Use

• At start of conductor workflow
• When resuming interrupted workflow
• Before Phase 1 (to check if already in progress)
• When user explicitly requests resumption

Instructions

Step 1: Check for State File

STATE_FILE=".claude/state/conductor.json"

if [ -f "$STATE_FILE" ]; then
  echo "📋 Found previous conductor session"

  # Validate JSON
  if ! jq empty "$STATE_FILE" 2>/dev/null; then
    echo "⚠️ State file corrupted - using git-only resumption"
    STATE_FOUND=false
  else
    STATE_FOUND=true

    # Load state
    SAVED_ISSUE=$(jq -r '.issue.number' "$STATE_FILE")
    SAVED_PHASE=$(jq -r '.currentPhase' "$STATE_FILE")
    SAVED_BRANCH=$(jq -r '.context.branchName' "$STATE_FILE")
    SAVED_PR=$(jq -r '.context.prNumber' "$STATE_FILE")
    SAVED_TIMESTAMP=$(jq -r '.timestamp' "$STATE_FILE")

    echo "   Issue: #$SAVED_ISSUE"
    echo "   Phase: $SAVED_PHASE"
    echo "   Branch: $SAVED_BRANCH"
    echo "   Last updated: $SAVED_TIMESTAMP"
  fi
else
  echo "ℹ️ No previous state file found - checking git state only"
  STATE_FOUND=false
fi

Step 2: Analyze Git State

# Get current branch
CURRENT_BRANCH=$(git branch --show-current)

# Check if on feature branch
if [[ "$CURRENT_BRANCH" =~ ^feature/issue-([0-9]+) ]]; then
  # Extract issue number from branch name
  BRANCH_ISSUE="${BASH_REMATCH[1]}"

  echo "🌿 Found feature branch: $CURRENT_BRANCH"
  echo "   Issue from branch: #$BRANCH_ISSUE"

  # Count commits on this branch
  COMMIT_COUNT=$(git rev-list --count development..HEAD 2>/dev/null || echo "0")
  echo "   Commits: $COMMIT_COUNT"

  # Check for uncommitted changes
  if [ -n "$(git status --porcelain)" ]; then
    HAS_CHANGES=true
    echo "   Uncommitted changes: Yes"
  else
    HAS_CHANGES=false
    echo "   Uncommitted changes: No"
  fi

  # Check if PR exists
  PR_NUMBER=$(gh pr list --head "$CURRENT_BRANCH" --json number --jq '.[0].number' 2>/dev/null)

  if [ -n "$PR_NUMBER" ] && [ "$PR_NUMBER" != "null" ]; then
    HAS_PR=true
    echo "   PR: #$PR_NUMBER"
  else
    HAS_PR=false
    echo "   PR: None"
  fi

  FEATURE_BRANCH_EXISTS=true
else
  echo "ℹ️ Not on feature branch (current: $CURRENT_BRANCH)"
  FEATURE_BRANCH_EXISTS=false
fi

Step 3: Determine Resumption Point

RESUME_PHASE=1
RESUME_STEP=""

if [ "$FEATURE_BRANCH_EXISTS" = true ]; then
  if [ "$HAS_PR" = true ]; then
    # PR exists → Resume from Phase 5 (Gemini Review)
    RESUME_PHASE=5
    RESUME_STEP="Monitor CI and Gemini review"
    SKIP_PHASES="1, 2, 3, 4"

  elif [ "$COMMIT_COUNT" -gt 0 ]; then
    # Commits exist but no PR → Resume from Phase 4 (PR Creation)
    # But first verify Phase 3 quality gates passed
    RESUME_PHASE=4
    RESUME_STEP="Create pull request"
    SKIP_PHASES="1, 2, 3"
    VERIFY_QUALITY=true

  elif [ "$HAS_CHANGES" = true ]; then
    # Uncommitted changes → Resume from Phase 3 (Quality Assurance)
    RESUME_PHASE=3
    RESUME_STEP="Run quality gates"
    SKIP_PHASES="1, 2 (partial)"

  else
    # Branch exists but no commits → Resume from Phase 2 Step 3 (Implementation)
    RESUME_PHASE=2
    RESUME_STEP="Implementation (branch already created)"
    SKIP_PHASES="1, 2 (steps 1-2)"
  fi
else
  # No feature branch → Start from Phase 1
  RESUME_PHASE=1
  RESUME_STEP="Issue discovery and planning"
  SKIP_PHASES="None"
fi

# Override with state file if more recent
if [ "$STATE_FOUND" = true ] && [ "$SAVED_PHASE" -gt "$RESUME_PHASE" ]; then
  RESUME_PHASE=$SAVED_PHASE
  echo "⚠️ State file indicates later phase - using Phase $SAVED_PHASE"
fi

Step 4: Validate Resumption

# If resuming from Phase 4+, verify quality gates passed
if [ "$RESUME_PHASE" -ge 4 ] && [ "$VERIFY_QUALITY" = true ]; then
  echo ""
  echo "⚠️ Resuming after implementation - validating quality gates..."

  # Quick validation checks
  VALIDATION_PASSED=true

  # Check if tests exist
  if ! npm run test --dry-run &>/dev/null; then
    echo "   ⚠️ Warning: No test script found"
  fi

  # Check for TypeScript errors
  if command -v tsc &>/dev/null; then
    if ! tsc --noEmit &>/dev/null; then
      echo "   ❌ TypeScript errors detected"
      VALIDATION_PASSED=false
    fi
  fi

  if [ "$VALIDATION_PASSED" = false ]; then
    echo ""
    echo "❌ Quality validation failed - resuming from Phase 3 instead"
    RESUME_PHASE=3
    RESUME_STEP="Re-run quality gates"
  fi
fi

Step 5: Return Resumption Data

{
  "resumption": {
    "detected": true,
    "phase": 4,
    "step": "Create pull request",
    "skipPhases": [1, 2, 3]
  },
  "state": {
    "source": "git+state_file",
    "stateFile": {
      "found": true,
      "issue": 137,
      "savedPhase": 3,
      "timestamp": "2025-10-21T..."
    },
    "git": {
      "branch": "feature/issue-137-dark-mode",
      "issue": 137,
      "commits": 5,
      "hasChanges": false,
      "hasPR": false
    }
  },
  "recommendation": {
    "action": "resume",
    "phase": 4,
    "reason": "Branch exists with commits but no PR - ready for PR creation",
    "validation": {
      "qualityGates": "not_verified",
      "recommendation": "Run Phase 3 validation before proceeding"
    }
  }
}

Output Format

Resume from Phase 1 (Fresh Start)

{
  "resumption": {
    "detected": false,
    "phase": 1,
    "step": "Issue discovery and planning",
    "skipPhases": []
  },
  "state": {
    "source": "none",
    "branch": "development"
  }
}

Resume from Phase 3 (Quality Gates)

{
  "resumption": {
    "detected": true,
    "phase": 3,
    "step": "Run quality gates",
    "skipPhases": [1, 2]
  },
  "state": {
    "source": "git",
    "git": {
      "branch": "feature/issue-137-dark-mode",
      "issue": 137,
      "commits": 0,
      "hasChanges": true
    }
  }
}

Resume from Phase 5 (Gemini Review)

{
  "resumption": {
    "detected": true,
    "phase": 5,
    "step": "Monitor CI and Gemini review",
    "skipPhases": [1, 2, 3, 4]
  },
  "state": {
    "source": "git+pr",
    "git": {
      "branch": "feature/issue-137-dark-mode",
      "issue": 137,
      "commits": 5,
      "hasPR": true,
      "prNumber": 45
    }
  }
}

Integration with Conductor

Used at the start of conductor workflow:

### BEFORE STARTING ANY WORKFLOW:

**Step 1: Check for Resumption**

Use `load-resumption-state` skill to analyze previous work:

Result: {
  "resumption": {
    "detected": true,
    "phase": 3,
    "skipPhases": [1, 2]
  }
}

**OUTPUT TO USER:**

🔄 RESUMPTION DETECTED

Current State: Branch: feature/issue-137-dark-mode Issue: #137 Commits: 5 PR: None

Detected Work: ✅ Phase 1: Planning ✅ Phase 2: Implementation → Phase 3: Quality Assurance

Resume from Phase 3? This will:

• Skip completed phases
• Continue with Quality Assurance
• Preserve existing commits

**If user confirms**: Jump to Phase 3
**If user declines**: Start fresh from Phase 1

Resumption Decision Matrix

| Git State | State File | Resume Phase | Skip Phases | |-----------|------------|--------------|-------------| | No feature branch | None | 1 | None | | Feature branch, no commits | Phase 2 | 2 (Step 3) | 1, 2 (partial) | | Feature branch + commits | Phase 3 | 3 | 1, 2 | | Feature branch + commits + changes | None | 3 | 1, 2 | | Feature branch + PR | Phase 5 | 5 | 1, 2, 3, 4 | | Feature branch + PR + CI passed | Phase 6 | 6 | 1, 2, 3, 4, 5 |

Related Skills

• save-workflow-state - Save state after each phase
• determine-resumption-phase - Advanced decision logic
• clear-workflow-state - Clean up after workflow completion

Error Handling

Corrupted State File

{
  "resumption": {
    "detected": true,
    "phase": 2,
    "warning": "State file corrupted - using git-only resumption"
  }
}

Conflicting State

{
  "resumption": {
    "detected": true,
    "phase": 3,
    "warning": "State file (Phase 2) conflicts with git (Phase 3) - using git state"
  }
}

Best Practices

1. Always check state before starting - Prevents duplicate work
2. Trust git state over state file - More reliable source of truth
3. Validate quality gates - When resuming Phase 4+
4. Inform user of resumption - Let them confirm before skipping phases
5. Log resumption decision - Include reasoning for debugging

Notes

• State file is supplemental - git is source of truth
• Resumption saves significant time on interrupted workflows
• User should always confirm resumption point
• Quality gates should be re-validated when resuming late phases