Research Protocol

# Research Protocol This document defines the research decision and execution flow. ## Overview ``` ┌─────────────────────────────────────────────────────────────┐ │ RESEARCH FLOW │ │ │ │ Step 4: Decide what to research │ │ - Codebase research? (existing patterns/conventions) │ │ - Web research? (best practices, SOTA approaches) │ │ │ │ Step 5: Execute research (parallel if both selected) │ │ - Subagents return results │ │ - Main Claude combines and writes claude-research.md │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Step 4: Research Decision ### 4.1 Read and Analyze the Spec File Read the spec file and extract potential research topics by identifying: - **Technologies mentioned** (React, Python, PostgreSQL, Redis, etc.) - **Feature types** (authentication, file upload, real-time sync, caching, etc.) - **Architecture patterns** (microservices, event-driven, serverless, etc.) - **Integration points** (third-party APIs, OAuth providers, payment gateways, etc.) Generate 3-5 research topic suggestions based on what you find. Format them as searchable queries with year for recency: - "React authentication patterns 2025" - "PostgreSQL full-text search best practices" - "Redis session storage patterns" If the spec is vague, fall back to generic options: - "General best practices for {detected_language/framework}" - "Security considerations for {feature_type}" ### 4.2 Ask About Codebase Research Use AskUserQuestion: ``` question: "Is there existing code I should research first?" header: "Codebase" options: - label: "Yes, research the codebase" description: "Analyze existing patterns, conventions, dependencies" - label: "No existing code" description: "This is a new project or standalone feature" ``` ### 4.3 Ask About Web Research Present the derived topics as multi-select options: ``` question: "Should I research current best practices for any of these topics?" header: "Web Research" multiSelect: true options: - label: "{derived_topic_1}" description: "Based on spec mention of {X}" - label: "{derived_topic_2}" description: "Based on spec mention of {Y}" - label: "{derived_topic_3}" description: "Based on spec mention of {Z}" ``` If user selects "Other", follow up to get custom topics. ### 4.4 Handle "No Research" Case If user selects no codebase AND no web research, skip step 5 entirely. --- ## Step 5: Execute Research ### Critical Pattern: Subagents Return Results, Parent Writes Files **DO NOT** have subagents write to files directly. This avoids race conditions and keeps control with the main context. ``` ┌─────────────────────────────────────────────────────────────┐ │ PARALLEL RESEARCH EXECUTION │ │ │ │ Task 1: Explore ──────────┐ │ │ (returns codebase │ │ │ findings as markdown) ├──→ Main Claude combines │ │ │ and writes single │ │ Task 2: Explore ──────────┘ claude-research.md │ │ (returns best practices │ │ findings as markdown) │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 5.1 Codebase Research (if selected) Launch Task tool with `subagent_type=Explore`: ``` Task tool: subagent_type: Explore description: "Research codebase patterns" prompt: | Research this codebase to understand: - Project structure and architecture - Existing patterns and conventions - Dependencies and how they're used - Testing setup (framework, patterns, how tests are run) Focus areas from user: {user_specified_areas_if_any} Return your findings as markdown. DO NOT write to any files. Return findings in your response. ``` ### 5.2 Web Research (if topics selected) Launch Task tool with `subagent_type=Explore`: ``` Task tool: subagent_type: Explore description: "Research best practices" prompt: | Research current best practices for the following topics: {selected_topics_list} For each topic: 1. Use WebSearch to find authoritative sources 2. Use WebFetch on promising results to extract recommendations 3. Cross-validate information across sources 4. Synthesize findings with clear recommendations Return your findings as markdown. Always cite sources with URLs. DO NOT write to any files. Return findings in your response. ``` ### 5.3 Parallel Execution If both codebase and web research are needed, launch **both Task tools in a single message**. ``` # Single message with multiple tool calls: [Task tool call 1: Explore subagent for codebase] [Task tool call 2: Explore subagent for web research] ``` Wait for both to complete, then combine results. ### 5.4 Combine Results and Write File After collecting results from all subagents, combine them into `/claude-research.md`. Structure the file however makes sense for the findings. --- ## Edge Cases | Case | Handling | |------|----------| | Spec file is vague | Present generic options based on detected language/framework | | User selects no research | Skip step 5, proceed to step 6 (interview) | | One subagent fails | Log warning, write file with only successful research | | Both subagents fail | Log error, ask user if they want to retry or proceed | | Only one research type | Run single subagent, write file with just that content |