/skill-deep-research

name: octopus-research
disable-model-invocation: true
effort: high
aliases:
  - research
  - deep-research
description: "Thorough research across multiple sources — use for complex topics needing broad synthesis"
context: fork
agent: Explore
task_management: true
task_dependencies:
  - skill-visual-feedback
  - skill-context-detection
execution_mode: enforced
pre_execution_contract:
  - interactive_questions_answered
  - visual_indicators_displayed
validation_gates:
  - orchestrate_sh_executed
  - synthesis_file_exists
trigger: |
  Use this skill when the user wants to "research this topic", "investigate how X works",
  "analyze the architecture", "explore different approaches to Y", or "what are the options for Z".

  Execution: orchestrate.sh probe via Bash tool (multi-provider research with available providers)

⚠️ 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.**

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:**

provider_status="$(bash "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}/scripts/helpers/check-providers.sh")"
[[ $'\n'"$provider_status"$'\n' == *$'\ncodex:available\n'* ]] && codex_status="Available ✓" || codex_status="Not installed ✗"
[[ $'\n'"$provider_status"$'\n' == *$'\nagy:available\n'* ]] && agy_status="Available ✓" || agy_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}
🟡 Antigravity CLI: ${agy_status}
🧭 Antigravity CLI: ${agy_status}
🔵 Claude: Available ✓ (Strategic synthesis)

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

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

**Validation:**

• If no external providers are available → STOP, suggest: `/octo:setup`
• If one or more external providers are available → Continue with available provider(s)

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

---

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

**Resolve the intensity first.** Use the `[intensity=quick|standard|deep]` token from the skill args when present. Otherwise map a `[breadth=…]` token the way `--breadth=` does (`light → quick`, `exhaustive → deep`; `quick`, `standard` and `deep` pass through unchanged). Otherwise map `depth_choice` (Quick overview → `quick`, Moderate depth → `standard`, Comprehensive or Deep dive → `deep`). Strip both tokens from the research question.

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

"${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${HOME}/.claude-octopus/plugin}}/scripts/orchestrate.sh" --intensity=<quick|standard|deep> probe \
  "<user's research question> (focus: ${focus_choice}; output: ${format_choice})"

orchestrate.sh takes the intensity only as the `--intensity=` flag. It has no `--depth`, `--focus` or `--format` options, and a bracket token such as `[intensity=deep]` is not an option either: either form would be read as prompt text and the probe would run at standard intensity.

**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 (MANDAT