deep-research Skill

Purpose: Multi-level autonomous investigation for complex JUCE plugin development problems using graduated research depth protocol.

Overview

Multi-level autonomous investigation (Level 1: 5 min local → Level 2: 30 min web → Level 3: 60 min parallel). Stops at first confident answer. User controls depth.

NEVER:

• Edit code files via Edit/Write/NotebookEdit tools

• Run build commands (npm, CMake, compiler)

• Modify contracts or configurations

• Implement any solutions

ONLY:

• Search for information (Grep, Glob, Read, WebSearch, WebFetch)

• Analyze existing code and documentation

• Generate reports and recommendations

• Present findings with decision menus

ALWAYS delegate implementation to plugin-improve skill via handoff protocol. Violation of this invariant breaks the system architecture.

<handoff_protocol target_skill="plugin-improve"> User selects option 1 ("Apply solution") from decision menu

<deep_research_action> When user selects "Apply solution":

• Output confirmation: "User selected: Apply solution. Invoking plugin-improve skill..."

• Use Skill tool to invoke plugin-improve directly

• STOP execution (no further implementation) </deep_research_action>

<context_passing> plugin-improve reads research findings from conversation history. plugin-improve skips Phase 0.5 investigation (already completed by deep-research). </context_passing>

Note: deep-research invokes plugin-improve directly via the Skill tool when user selects "Apply solution". This ensures the handoff happens automatically without requiring main conversation orchestration.

Why separation matters:

• Research uses Opus + extended thinking (expensive)

• Implementation needs codebase context (different focus)

• Clear decision gate between "here are options" and "making changes"

• Research can't break anything (safe exploration)

Entry Points

Invoked by: troubleshooter (Level 4), /research [topic] , build-automation "Investigate", or natural language ("research [topic]").

Parameters: Topic/question (required), context (optional: plugin name, stage, error), starting level (optional: /research [topic] --level 2 to skip Level 1).

<critical_sequence name="graduated_research_protocol" skip_prevention="strict">

Find quick answer from local knowledge base or JUCE API docs

<required_steps> 1. Search local troubleshooting docs 2. Quick Context7 lookup 3. Assess confidence </required_steps>

<exit_conditions> IF confidence = HIGH: Present decision menu, ALLOW user to proceed ELSE: MUST escalate to Level 2 (no skip option) </exit_conditions>

Deep-dive JUCE docs, forums, GitHub for authoritative answers

<required_steps> 1. Context7 deep-dive (advanced queries, cross-references) 2. JUCE forum search via WebSearch 3. GitHub issue search (juce-framework/JUCE) 4. Synthesize findings from multiple sources </required_steps>

<exit_conditions> IF confidence IN [HIGH, MEDIUM]: Present decision menu ELSE IF confidence = LOW OR novel_problem = true: MUST escalate to Level 3 </exit_conditions>

Parallel subagent investigation for novel/complex problems

<model_requirements> MUST use: claude-opus-4-1-20250805 MUST enable: extended-thinking with 15k budget NEVER use: Sonnet (insufficient synthesis capacity) </model_requirements>

<required_steps> 1. Switch to Opus + extended thinking 2. Identify 2-3 research approaches 3. Spawn parallel subagents via Task tool (NOT serial) 4. Synthesize findings with extended thinking 5. Generate comprehensive report </required_steps>

<exit_conditions> ALWAYS: Present decision menu (no further escalation possible) </exit_conditions>

<enforcement_rules>

• NEVER skip Level 1 unless user explicitly requests starting at Level 2/3 (via /research [topic] --level 2 or "Start with Level 2 investigation of [topic]")

• NEVER use serial investigation at Level 3 (must be parallel)

• NEVER use Sonnet at Level 3 (must be Opus)

• NEVER forget extended thinking at Level 3

• NEVER implement solutions (always delegate to plugin-improve) </enforcement_rules> </critical_sequence>

Level 1: Quick Check (5-10 min, Sonnet, no extended thinking)

Goal: Find quick answer from local knowledge base or JUCE API docs

Sources: Local troubleshooting docs, Context7 JUCE documentation

Exit criteria: HIGH confidence solution → present decision menu, otherwise escalate to Level 2

See references/research-protocol.md#level-1-quick-check for detailed process.

Level 2: Moderate Investigation (15-30 min, Sonnet, no extended thinking)

Goal: Deep-dive JUCE docs, forums, GitHub for authoritative answers

Sources: Context7 deep-dive, JUCE forum search, GitHub issue search

Exit criteria: MEDIUM-HIGH confidence solution → present decision menu, otherwise escalate to Level 3

See references/research-protocol.md#level-2-moderate-investigation for detailed process.

Level 3: Deep Research (30-60 min, Opus, extended thinking 15k budget)

Goal: Parallel subagent investigation for novel/complex problems

Model requirements: claude-opus-4-1-20250805 with extended-thinking (15k budget)

Process: Spawn 2-3 parallel research subagents via Task tool, synthesize findings

Exit criteria: ALWAYS present decision menu (no further escalation)

See references/research-protocol.md#level-3-deep-research for detailed process.

Report Generation

Each level generates a structured report using templates in assets/ :

• Level 1: assets/level1-report-template.md

• Level 2: assets/level2-report-template.md

• Level 3: assets/level3-report-template.md

Reports include: findings summary, confidence assessment, recommended solution, and source references.

Progress tracking: Use assets/research-progress.md template to track investigation progress across levels.

<state_requirement name="checkpoint_protocol"> At the end of each level (when presenting findings), MUST:

• Present decision menu (numbered list format, NOT AskUserQuestion tool)

• WAIT for user response (NEVER auto-proceed)

• Route based on selection:

<response_handler option="1" action="apply_solution"> User selects option 1 ("Apply solution")

• Output confirmation: "User selected: Apply solution. Invoking plugin-improve skill..."

• Use Skill tool to invoke plugin-improve

• STOP execution (no further implementation)

</response_handler>

<response_handler option="2" action="review_findings"> User selects option 2 ("Review full findings")

• Display complete research report

• Re-present decision menu

• WAIT for new selection

</response_handler>

<response_handler option="3" action="escalate"> User selects option 3 ("Escalate to next level")

• Proceed to next level (Level 1 → Level 2 → Level 3)

• If already at Level 3, inform user no further escalation available

• Continue with next level's process

</response_handler>

<response_handler option="other" action="clarify"> User provides custom response

• Ask for clarification

• Re-present decision menu with context

• WAIT for selection

</response_handler>

Decision Menus

After each level, present decision menu using checkpoint protocol format:

Example (Level 1 - HIGH confidence):

✓ Level 1 complete (found solution in local docs)

Solution: [Brief description of solution] Source: troubleshooting/[category]/[file].md Confidence: HIGH (exact match)

What's next?

1. Apply solution (recommended)
2. Review full findings
3. Continue deeper - Escalate to Level 2
4. Other

Choose (1-4): _

Example (Level 2 - MEDIUM confidence):

✓ Level 2 complete (found 2 potential solutions)

Recommended: [Solution 1 name] Alternative: [Solution 2 name] Confidence: MEDIUM (verified by JUCE forum + docs)

What's next?

1. Apply recommended solution
2. Review all findings
3. Try alternative approach
4. Continue deeper - Escalate to Level 3
5. Other

Choose (1-5): _

Example (Level 3 - comprehensive investigation):

✓ Level 3 complete (parallel investigation)

Investigated 3 approaches:

• Approach A: [Brief description] (recommended)
• Approach B: [Brief description] (viable alternative)
• Approach C: [Brief description] (not recommended)

Confidence: HIGH after synthesis

What's next?

1. Apply recommended solution (recommended)
2. Review detailed comparison
3. Try alternative approach B
4. Document findings
5. Other

Choose (1-5): _

NEVER use AskUserQuestion tool for decision menus. Always use inline numbered lists with "Choose (1-N): _" format matching checkpoint protocol.

See <state_requirement name="checkpoint_protocol"> below for response handling.

Integration Points

See references/integrations.md for troubleshooter and troubleshooting-docs integration details.

Error Handling

See references/error-handling.md for timeout, failure, and fallback patterns.