deep-research

# 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. --- <invariant type="read_only_protocol" severity="critical"> This skill is READ-ONLY and ADVISORY ONLY. 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. </invariant> <handoff_protocol target_skill="plugin-improve"> <trigger>User selects option 1 ("Apply solution") from decision menu</trigger> <deep_research_action> When user selects "Apply solution": 1. Output confirmation: "User selected: Apply solution. Invoking plugin-improve skill..." 2. Use Skill tool to invoke plugin-improve directly 3. 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> <enforcement> deep-research NEVER implements. Only plugin-improve implements. deep-research MUST invoke plugin-improve via Skill tool. </enforcement> </handoff_protocol> **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"> <level number="1" name="quick_check" max_time_minutes="10"> <goal>Find quick answer from local knowledge base or JUCE API docs</goal> <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> </level> <level number="2" name="moderate_investigation" max_time_minutes="30"> <prerequisite>Level 1 completed OR user manually started at Level 2</prerequisite> <goal>Deep-dive JUCE docs, forums, GitHub for authoritative answers</goal> <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> </level> <level number="3" name="deep_research" max_time_minutes="60"> <prerequisite>Level 2 completed OR user manually started at Level 3</prerequisite> <goal>Parallel subagent investigation for novel/complex problems</goal> <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> </level> <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: 1. Present decision menu (numbered list format, NOT AskUserQuestion tool) 2. WAIT for user response (NEVER auto-proceed) 3. Route based on selection: <response_handler option="1" action="apply_solution"> <condition>User selects option 1 ("Apply solution")</condition> <action> 1. Output confirmation: "User selected: Apply solution. Invoking plugin-improve skill..." 2. Use Skill tool to invoke plugin-improve 3. STOP execution (no further implementation) </action> </response_handler> <response_handler option="2" action="review_findings"> <condition>User selects option 2 ("Review full findings")</condition> <action> 1. Display complete research report 2. Re-present decision menu 3. WAIT for new selection </action> </response_handler> <response_handler option="3" action="escalate"> <condition>User selects option 3 ("Escalate to next level")</condition> <action> 1. Proceed to next level (Level 1 → Level 2 → Level 3) 2. If already at Level 3, inform user no further escalation available 3. Continue with next level's process </action> </response_handler> <response_handler option="other" action="clarify"> <condition>User provides custom response</condition> <action> 1. Ask for clarification 2. Re-present decision menu with context 3. WAIT for selection </action> </response_handler> <enforcement> NEVER auto-proceed to implementation. NEVER skip decision menu. ALWAYS wait for user response before continuing. </enforcement> </state_requirement> ## 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](references/integrations.md) for troubleshooter and troubleshooting-docs integration details. --- ## Error Handling See [references/error-handling.md](references/error-handling.md) for timeout, failure, and fallback patterns. ---