octopus-research

## ⚠️ EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)

<HARD-GATE>
**CRITICAL: You MUST call orchestrate.sh via the Bash tool. Do NOT research the topic yourself.
Do NOT use Task agents, web search, or your own knowledge as a substitute. The ONLY valid
execution path is: Bash → orchestrate.sh probe. If you produce research findings without
a Bash call to orchestrate.sh, you have violated this contract.**
</HARD-GATE>

This skill uses **ENFORCED execution mode**. You MUST follow this exact sequence.

### STEP 1: Interactive Questions (BLOCKING - Answer before proceeding)

**You MUST call AskUserQuestion with all 3 questions below BEFORE any other action.**

```javascript
AskUserQuestion({
  questions: [
    {
      question: "How deep should the research go?",
      header: "Research Depth",
      multiSelect: false,
      options: [
        {label: "Quick overview (Recommended)", description: "1-2 min, surface-level"},
        {label: "Moderate depth", description: "2-3 min, standard"},
        {label: "Comprehensive", description: "3-4 min, thorough"},
        {label: "Deep dive", description: "4-5 min, exhaustive"}
      ]
    },
    {
      question: "What's your primary focus area?",
      header: "Primary Focus",
      multiSelect: false,
      options: [
        {label: "Technical implementation (Recommended)", description: "Code patterns, APIs"},
        {label: "Best practices", description: "Industry standards"},
        {label: "Ecosystem & tools", description: "Libraries, community"},
        {label: "Trade-offs & comparisons", description: "Pros/cons analysis"}
      ]
    },
    {
      question: "How should the output be formatted?",
      header: "Output Format",
      multiSelect: false,
      options: [
        {label: "Detailed report (Recommended)", description: "Comprehensive write-up"},
        {label: "Summary", description: "Concise findings"},
        {label: "Comparison table", description: "Side-by-side analysis"},
        {label: "Recommendations", description: "Actionable next steps"}
      ]
    }
  ]
})
```

**Capture user responses as:**
- `depth_choice` = user's depth selection
- `focus_choice` = user's focus selection
- `format_choice` = user's format selection

**DO NOT PROCEED TO STEP 2 until all questions are answered.**

**Optional**: If **claude-mem** is installed, use its MCP tools (`search`) to check for relevant past research on this topic before launching new research agents.

---

### STEP 2: Provider Detection & Visual Indicators (MANDATORY)

**Check provider availability:**

```bash
command -v codex &> /dev/null && codex_status="Available ✓" || codex_status="Not installed ✗"
command -v gemini &> /dev/null && gemini_status="Available ✓" || gemini_status="Not installed ✗"
```

**Display this banner BEFORE orchestrate.sh execution:**

```
🐙 **CLAUDE OCTOPUS ACTIVATED** - Multi-provider research mode
🔍 Discover Phase: [Brief description of research topic]

Provider Availability:
🔴 Codex CLI: ${codex_status}
🟡 Gemini CLI: ${gemini_status}
🔵 Claude: Available ✓ (Strategic synthesis)

Research Parameters:
📊 Depth: ${depth_choice}
🎯 Focus: ${focus_choice}
📝 Format: ${format_choice}

💰 Estimated Cost: $0.01-0.05
⏱️  Estimated Time: 2-5 minutes
```

**Validation:**
- If BOTH Codex and Gemini unavailable → STOP, suggest: `/octo:setup`
- If ONE unavailable → Continue with available provider(s)
- If BOTH available → Proceed normally

**DO NOT PROCEED TO STEP 3 until banner displayed.**

---

### STEP 3: Execute orchestrate.sh (MANDATORY - Use Bash Tool)

**You MUST execute this command via the Bash tool:**

```bash
${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh probe "<user's research question>" \
  --depth "${depth_choice}" \
  --focus "${focus_choice}" \
  --format "${format_choice}"
```

**CRITICAL: You are PROHIBITED from:**
- ❌ Researching directly without calling orchestrate.sh
- ❌ Using web search instead of orchestrate.sh
- ❌ Claiming you're "simulating" the workflow
- ❌ Proceeding to Step 4 without running this command

**This is NOT optional. You MUST use the Bash tool to invoke orchestrate.sh.**

---

### STEP 4: Verify Execution (MANDATORY - Validation Gate)

**After orchestrate.sh completes, verify it succeeded:**

```bash
# Find the latest synthesis file (created within last 10 minutes)
SYNTHESIS_FILE=$(find ~/.claude-octopus/results -name "probe-synthesis-*.md" -mmin -10 2>/dev/null | head -n1)

if [[ -z "$SYNTHESIS_FILE" ]]; then
  echo "❌ VALIDATION FAILED: No synthesis file found"
  echo "orchestrate.sh did not execute properly"
  exit 1
fi

echo "✅ VALIDATION PASSED: $SYNTHESIS_FILE"
cat "$SYNTHESIS_FILE"
```

**If validation fails:**
1. Report error to user
2. Show logs from `~/.claude-octopus/logs/`
3. DO NOT proceed with presenting results
4. DO NOT substitute with direct research

---

### STEP 5: Present Results (Only After Steps 1-4 Complete)

Read the synthesis file and format according to `format_choice`:
- **Summary**: 2-3 paragraph overview with key recommendations
- **Detailed report**: Full synthesis with all perspectives
- **Comparison table**: Side-by-side analysis in markdown table
- **Recommendations**: Actionable next steps with rationale

**Include attribution:**
```
---
*Multi-AI Research powered by Claude Octopus*
*Providers: 🔴 Codex | 🟡 Gemini | 🔵 Claude*
*Full synthesis: $SYNTHESIS_FILE*
```

---

## Task Management Integration

Create tasks to track execution progress:

```javascript
// At start of skill execution
TaskCreate({
  subject: "Execute deep research with multi-AI providers",
  description: "Run orchestrate.sh probe with Codex and Gemini for deep research",
  activeForm: "Running multi-AI deep research"
})

// Mark in_progress when calling orchestrate.sh
TaskUpdate({taskId: "...", status: "in_progress"})

// Mark completed ONLY after synthesis file verified
TaskUpdate({taskId: "...", status: "completed"})
```

## Error Handling

If any step fails:
- **Step 1 (Questions)**: Cannot proceed