microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/rpi/task-researcher.md
153lines · modecode
| 1 | --- |
| 2 | title: Task Researcher Guide |
| 3 | description: Use the Task Researcher custom agent to conduct deep, evidence-based research before coding |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-01-24 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - task researcher |
| 9 | - rpi workflow |
| 10 | - research phase |
| 11 | - github copilot |
| 12 | estimated_reading_time: 4 |
| 13 | --- |
| 14 | |
| 15 | The Task Researcher custom agent transforms uncertainty into verified knowledge through deep, autonomous research. It investigates your codebase, external documentation, and APIs to create evidence-backed recommendations. |
| 16 | |
| 17 | ## When to Use Task Researcher |
| 18 | |
| 19 | Escalate to Task Researcher when your task involves: |
| 20 | |
| 21 | * 🔄 **Multi-file changes** requiring coordination |
| 22 | * 📚 **New patterns or frameworks** you haven't used before |
| 23 | * 🔌 **External API integrations** with authentication or complex workflows |
| 24 | * ❓ **Unclear requirements** needing investigation |
| 25 | * 🏗️ **Architecture decisions** affecting multiple components |
| 26 | |
| 27 | ## What Task Researcher Does |
| 28 | |
| 29 | 1. **Investigates** using workspace search, file reads, and external tools |
| 30 | 2. **Documents** findings with evidence, sources, and line references |
| 31 | 3. **Evaluates** alternatives with benefits and trade-offs |
| 32 | 4. **Recommends** ONE approach per technical scenario |
| 33 | 5. **Outputs** a comprehensive research document |
| 34 | |
| 35 | > [!NOTE] |
| 36 | > **Why the constraint matters:** Task Researcher knows it will never write the code. This single constraint transforms its behavior—it searches for existing patterns instead of inventing new ones, cites specific files as evidence, and questions its own assumptions because it can't hide them in implementation. |
| 37 | |
| 38 | ## Output Artifact |
| 39 | |
| 40 | Task Researcher creates a research document at: |
| 41 | |
| 42 | ```text |
| 43 | .copilot-tracking/research/{{YYYY-MM-DD}}-<topic>-research.md |
| 44 | ``` |
| 45 | |
| 46 | This document includes: |
| 47 | |
| 48 | * Scope and success criteria |
| 49 | * Evidence log with sources |
| 50 | * Code examples from the codebase |
| 51 | * External research findings |
| 52 | * Recommended approach with rationale |
| 53 | |
| 54 | ## How to Use Task Researcher |
| 55 | |
| 56 | ### Option 1: Use the Prompt Shortcut (Recommended) |
| 57 | |
| 58 | Type `/task-research <topic>` in GitHub Copilot Chat where `<topic>` describes what you want to research: |
| 59 | |
| 60 | ```text |
| 61 | /task-research Azure Blob Storage integration for Python pipelines |
| 62 | ``` |
| 63 | |
| 64 | This automatically switches to Task Researcher and begins the research protocol. |
| 65 | |
| 66 | ### Option 2: Select the Custom Agent Manually |
| 67 | |
| 68 | 1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) |
| 69 | 2. Click the agent picker dropdown at the top |
| 70 | 3. Select **Task Researcher** |
| 71 | 4. Describe your task |
| 72 | |
| 73 | ### Step 2: Describe Your Task |
| 74 | |
| 75 | Provide context about what you're trying to accomplish. Be specific about: |
| 76 | |
| 77 | * The problem you're solving |
| 78 | * Technologies or patterns involved |
| 79 | * Any constraints or requirements |
| 80 | |
| 81 | ### Step 3: Let It Research |
| 82 | |
| 83 | Task Researcher works autonomously for 20-60 minutes. It will: |
| 84 | |
| 85 | * Search your codebase for patterns |
| 86 | * Read relevant files and documentation |
| 87 | * Use external tools (Context7, Azure docs, etc.) |
| 88 | * Create the research document |
| 89 | |
| 90 | ### Step 4: Review the Research |
| 91 | |
| 92 | When complete, Task Researcher provides: |
| 93 | |
| 94 | * Summary of key findings |
| 95 | * Location of the research document |
| 96 | * Next steps for planning phase |
| 97 | |
| 98 | ## Example Prompt |
| 99 | |
| 100 | ```text |
| 101 | I need to add Azure Blob Storage integration to our Python data pipeline. |
| 102 | The pipeline currently writes to local disk in src/pipeline/writers/. |
| 103 | Research: |
| 104 | - Azure SDK for Python blob storage options |
| 105 | - Authentication approaches (managed identity vs connection string) |
| 106 | - Streaming uploads for files > 1GB |
| 107 | - Error handling and retry patterns |
| 108 | |
| 109 | Focus on approaches that match our existing patterns in the codebase. |
| 110 | ``` |
| 111 | |
| 112 | ## Tips for Better Research |
| 113 | |
| 114 | ✅ **Do:** |
| 115 | |
| 116 | * Provide specific technical context |
| 117 | * Mention existing code patterns to match |
| 118 | * List specific questions to answer |
| 119 | * Include constraints (performance, security, etc.) |
| 120 | |
| 121 | ❌ **Don't:** |
| 122 | |
| 123 | * Ask for implementation (that's Task Implementor's job) |
| 124 | * Skip research for complex tasks |
| 125 | * Provide vague descriptions |
| 126 | |
| 127 | ## Common Pitfalls |
| 128 | |
| 129 | | Pitfall | Solution | |
| 130 | |----------------------|--------------------------------------------------| |
| 131 | | Research too broad | Focus on specific technical questions | |
| 132 | | Skipping research | Always research multi-file or unfamiliar changes | |
| 133 | | Not reviewing output | Read the research doc before planning | |
| 134 | |
| 135 | ## Next Steps |
| 136 | |
| 137 | After Task Researcher completes: |
| 138 | |
| 139 | 1. **Review** the research document in `.copilot-tracking/research/` |
| 140 | 2. **Clear context** using `/clear` or starting a new chat |
| 141 | 3. **Proceed to planning** with [Task Planner](task-planner.md) |
| 142 | |
| 143 | Pass the research document path to Task Planner so it can create an actionable implementation plan. |
| 144 | |
| 145 | > [!TIP] |
| 146 | > Use the **📋 Create Plan** handoff button when available to transition directly to Task Planner with context. |
| 147 | |
| 148 | --- |
| 149 | |
| 150 | <!-- markdownlint-disable MD036 --> |
| 151 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 152 | then carefully refined by our team of discerning human reviewers.* |
| 153 | <!-- markdownlint-enable MD036 --> |
| 154 | |