deep-research

deep-research Skill

Purpose: Multi-level autonomous investigation for complex VCV Rack module development problems using graduated research depth protocol.

Overview

This skill performs thorough research on technical problems by consulting multiple knowledge sources with automatic escalation based on confidence. Starts fast (5 min local lookup) and escalates as needed (up to 60 min parallel investigation).

Why graduated protocol matters:

Most problems have known solutions (Level 1: 5 min). Complex problems need deep research (Level 3: 60 min). Graduated protocol prevents over-researching simple problems while ensuring complex problems get thorough investigation.

Key innovation: Stops as soon as confident answer found. User controls depth via decision menus.

---

Read-Only Protocol

CRITICAL: This skill is read-only and advisory only. It NEVER:

• Edits code files
• Runs builds
• Modifies contracts or configurations
• Implements solutions

Workflow handoff:

1. Research completes and presents findings with decision menu
2. User selects "Apply solution"
3. Output routing instruction: "User selected: Apply solution. Next step: Invoke module-improve skill."
4. Main conversation (orchestrator) sees routing instruction and invokes module-improve skill
5. module-improve reads research findings from conversation history
6. module-improve handles all implementation (with versioning, backups, testing)

Note: The routing instruction is a directive to the main conversation. When the orchestrator sees "Invoke module-improve skill", it will use the Skill tool to invoke module-improve. This is the standard handoff protocol.

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 agent (Level 4 investigation)
• User manual: /research [topic]
• build-automation "Investigate" option
• Natural language: "research [topic]", "investigate [problem]"

Entry parameters:

• Topic/question: What to research
• Context (optional): Module name, stage, error message
• Starting level (optional): Skip to Level 2/3 if explicitly requested

---

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

Goal: Find solution in local knowledge base or basic Rack SDK docs

Process

1. Parse research topic/question

   • Extract keywords
   • Identify VCV Rack components involved
   • Classify problem type (build, runtime, API usage, panel, CV, etc.)

2. Search local troubleshooting docs:

   # Search by keywords
   grep -r "[topic keywords]" troubleshooting/
   
   # Check relevant categories
   ls troubleshooting/[category]/
   
   # Search for module-specific or general issues
   

3. Check Rack SDK documentation for direct answers:

   • Query for relevant class/API
   • Check method signatures
   • Review basic usage examples
   • Look for known limitations

4. Assess confidence:

   • HIGH: Exact match in local docs OR clear API documentation
   • MEDIUM: Similar issue found but needs adaptation
   • LOW: No relevant matches or unclear documentation

5. Decision point:

   If HIGH confidence:

   ✓ Level 1 complete (found solution)
   
   Solution: [Brief description]
   Source: [Local doc or Rack SDK API]
   
   What's next?
   1. Apply solution (recommended)
   2. Review details - See full explanation
   3. Continue deeper - Escalate to Level 2 for more options
   4. Other
   

   If MEDIUM/LOW confidence: Auto-escalate to Level 2 with notification:

   Level 1: No confident solution found
   Escalating to Level 2 (moderate investigation)...
   

---

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

Goal: Find authoritative answer through comprehensive documentation and community knowledge

Process

1. Rack SDK deep-dive:

   • Full module documentation
   • Code examples and patterns
   • Related classes and methods
   • Best practices sections
   • Migration guides (if version-related)

2. VCV Rack community forum search via WebSearch:

   Query: "site:community.vcvrack.com [topic]"
   
   Look for:
   - Recent threads (last 2 years)
   - Accepted solutions
   - VCV team responses
   - Multiple user confirmations
   

3. GitHub issue search:

   Query: "site:github.com/VCVRack/Rack [topic]"
   
   Look for:
   - Closed issues with solutions
   - Pull requests addressing problem
   - Code examples in discussions
   - Version-specific fixes
   

4. Synthesize findings:

   • Compare multiple sources
   • Verify version compatibility (Rack SDK 2.x)
   • Assess solution quality (proper fix vs workaround)
   • Identify common recommendations

5. Decision point:

   If HIGH/MEDIUM confidence:

   ✓ Level 2 complete (found N solutions)
   
   Investigated sources:
   - Rack SDK docs: [Finding]
   - VCV Community: [N threads]
   - GitHub: [N issues]
   
   Solutions found:
   1. [Solution 1] (recommended)
   2. [Solution 2] (alternative)
   
   What's next?
   1. Apply recommended solution
   2. Review all options - Compare approaches
   3. Continue deeper - Escalate to Level 3 (parallel investigation)
   4. Other
   

   If LOW confidence OR novel problem: Auto-escalate to Level 3 with notification:

   Level 2: Complex problem detected (requires original implementation)
   Escalating to Level 3 (deep research with parallel investigation)...
   
   Switching to Opus model + extended thinking (may take up to 60 min)
   

---

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

Goal: Comprehensive investigation with parallel subagent research for novel/complex problems

Process

1. Switch to Opus model with extended thinking:

   extended_thinking: true
   thinking_budget: 15000
   timeout: 3600 # 60 min
   

2. Identify research approaches:

   Analyze problem and determine 2-3 investigation paths:

   For DSP algorithm questions:

   • Algorithm A investigation (e.g., anti-aliasing methods)
   • Algorithm B investigation (e.g., oversampling approach)
   • Commercial implementation research (industry standards)

   For novel feature implementation:

   • VCV Rack native approach (using built-in APIs)
   • External library approach (e.g., integration patterns)
   • Custom implementation approach (from scratch)

   For performance optimization:

   • Algorithm optimization (better complexity)
   • Caching/pre-computation (trade memory for CPU)
   • SIMD/parallel processing (vectorization)

3. Spawn parallel research subagents:

   Use Task tool to spawn 2-3 specialized research agents in fresh contexts:

   // Example: CV scaling research for V/Oct tracking
   
   Task(
     (subagent_type = "general-purpose"),
     (description = "Research V/Oct standard"),
     (prompt = `
       Investigate 1V/octave CV standard for pitch tracking in VCV Rack.
   
       Research:
       1. Voltage-to-frequency conversion formula
       2. VCV Rack API support (dsp::FREQ_* constants?)
       3. Implementation complexity (1-5 scale)
       4. Common pitfalls and edge cases
       5. Reference implementations
       6. Code examples
   
       Return structured findings:
       {
         "approach": "V/Oct conversion",
         "rack_support": "description",
         "complexity": 2,
         "formula": "...",
         "pros": ["...", "..."],
         "cons": ["...", "..."],
         "references": ["...", "..."]
       }
     `)
   );
   
   Task(
     (subagent_type = "general-purpose"),
     (description = "Research exponential FM"),
     (prompt = `
       Investigate exponential frequency modulation for VCV Rack oscillators.
   
       Research:
       1. Linear vs exponential FM differences
       2. VCV Rack conventions (how much FM range?)
       3. Implementation complexity (1-5 scale)
       4. CPU performance characteristics
       5. Code examples or references
   
       Return structured findings:
       {
         "approach": "Exponential FM",
         "rack_conventions": "description",
         "complexity": 3,
         "typical_range": "...",
         "pros": ["...", "..."],
         "cons": ["...", "..."],
         "references": ["...", "..."]
       }
     `)
   );
   
   Task(
     (subagent_type = "general-purpose"),
     (description = "Research polyphony implementation"),
     (prompt = `
       Research polyphonic voice allocation for VCV Rack modules.
   
       Investigate:
       1. VCV Rack polyphony API (16 channels max)
       2. Voice allocation strategies
       3. Common patterns from existing modules
       4. Performance considerations
   
       Return structured findings:
       {
         "approach": "Polyphony",
         "max_channels": 16,
         "allocation_strategy": "...",
         "rack_patterns": "...",
         "references": ["...", "..."]
       }
     `)
   );
   

   Each subagent:

   • Runs in fresh context (no accumulated conversation)
   • Has focused research goal
   • Returns structured findings
   • Takes 10-20 minutes
   • Runs in parallel (3 agents = 20 min total, not 60 min)

4. Main context synthesis (extended thinking):

   After all subagents return, use extended thinking to synthesize:

   • Aggregate findings from all subagents
   • Compare approaches:
     • Pros/cons for each
     • Implementation complexity (1-5 scale)
     • CPU cost vs quality trade-offs
     • VCV Rack integration ease
   • Recommend best fit:
     • For this specific use case
     • Considering complexity budget
     • Balancing CPU and quality
   • Implementation roadmap:
     • Step-by-step approach
     • VCV Rack APIs to use
     • Potential pitfal

---

Content truncated.