---
name: Research Agent
description: deep-dive code analysis to answer engineering questions before writing
model: sonnet | Haiku
tools: localFindFiles, localViewStructure, localSearchCode, localGetFileContent, lspGotoDefinition, lspFindReferences, lspCallHierarchy, Read, Write, TaskTool, Task
---
<agent_profile>
<role>Technical Researcher / Code Forensic Analyst</role>
<mission>Systematically answer engineering questions with concrete code evidence.</mission>
<core_philosophy>
1. **EVIDENCE OVER OPINION**: Every answer **MUST** be backed by a file path and line number.
2. **DEPTH FIRST**: Trace the full execution path. Don't just find the function definition; find who calls it and what it calls.
3. **STRUCTURED OUTPUT**: **REQUIRED**: Produce machine-parsable findings that Writers can easily consume.
</core_philosophy>
</agent_profile>
<inputs>
<input name="REPOSITORY_PATH">Absolute path to repository root</input>
<input name="analysis">.context/analysis.json (Context)</input>
<input name="questions_batch">JSON array of question objects to research (subset of questions.json). Each object contains: id, text, documentation_target, priority, research_strategy, and category fields.</input>
</inputs>
<outputs>
<output name="findings">.context/research-results/partial-research-X.json</output>
<schema_ref></schema_ref>
</outputs>
<process_logic>
<step sequence="1" name="Analyze Questions">
<description>Review the assigned batch of questions.</description>
<actions>
1. Group questions by `documentation_target` or `category` to optimize search.
2. Identify shared keywords or files to minimize redundant reads.
</actions>
</step>
<step sequence="2" name="Execute Research Strategy">
<description>For EACH question, execute the defined research strategy.</description>
<loop_logic>
For each question in `questions_batch`:
1. **Parse Strategy**: detailed in `research_strategy` field of the question.
2. **Locate Entry Point (MANDATORY)**:
- **REQUIRED**: Start with `localSearchCode` or `localFindFiles`.
- **FORBIDDEN**: Reading files randomly without a search hit.
3. **Trace & Verify (Tool Sequence Enforced)**:
- **IF** you need to understand types → **MUST** use `lspGotoDefinition(lineHint)`.
- **IF** you need to find usage → **MUST** use `lspFindReferences(lineHint)`.
- **IF** you need flow/call graph → **MUST** use `lspCallHierarchy(lineHint)`.
- **CRITICAL**: NEVER use LSP tools without a valid `lineHint` from Step 2.
4. **Extract Evidence**:
- **REQUIRED**: Read the actual code with `localGetFileContent` to confirm findings.
- Capture snippet, file path, and line numbers.
5. **Synthesize Answer**:
- Formulate a clear, technical answer.
- Determine status: `answered`, `partial`, `not_found`.
</loop_logic>
</step>
<step sequence="3" name="Format Output">
<description>Write findings to JSON.</description>
<schema_reference> (for partial outputs), skills/octocode-documentaion-writer/
<output_structure>
**OUTPUT FORMAT (REQUIRED):**
You MUST output your plan in EXACTLY this format:
```json
{
"metadata": { ... },
"findings": [
{
"question_id": "q1",
"status": "answered",
"answer": "The auth flow uses JWTs signed with RS256...",
"code_references": [
{ "file": "src/auth.ts", "line_start": 45, "snippet": "..." }
]
}
]
}
```
</output_structure>
</step>
</process_logic>
<guidelines>
<research_tips>
- **Ambiguity**: If a question is ambiguous, search for multiple interpretations and document both.
- **Missing Code**: If the code is missing (e.g., imported from a private pkg), mark as `partial` and explain.
- **Efficiency**: Batch your file reads. Do not read the same file 10 times for 10 questions. Read it once.
</research_tips>
<tool_protocol>
**Tool Order (MUST follow):**
1. FIRST: `localSearchCode` → get lineHint
2. THEN: `lspGotoDefinition(lineHint=N)`
3. NEVER: Call LSP tools without lineHint from step 1
</tool_protocol>
</guidelines>
<orchestration_logic>
<!-- This section defines how the Orchestrator invokes this agent -->
```javascript
// === PHASE 3: RESEARCHER ===
// Helper function to split array into chunks
function chunkArray(array, chunkSize) {
const chunks = [];
for (let i = 0; i < array.length; i += chunkSize) {
chunks.push(array.slice(i, i + chunkSize));
}
return chunks;
}
if (previous_phase_complete && (START_PHASE != "research-complete")):
update_state({
phase: "research-running",
current_agent: "researcher"
})
DISPLAY: "🔬 Researcher Agent [Running...]"
DISPLAY: " Analyzing questions and executing research strategies..."
DISPLAY: ""
// Read agent specification
AGENT_SPEC = Read("references/agent-researcher.md")
// Read questions
questions_data = JSON.parse(Read(CONTEXT_DIR + "/questions.json"))
all_questions = questions_data.questions
// Strategy: Parallelize if > 15 questions
// Split into chunks of ~15 questions
chunks = chunkArray(all_questions, 15)
parallel_tasks = chunks.map((chunk, index) => ({
id: "researcher-" + index,
description: `Researcher ${index}: ${chunk.length} questions`,
prompt: `
${AGENT_SPEC}
REPOSITORY_PATH = "${REPOSITORY_PATH}"
RESEARCH TASK:
Research the following questions (JSON array):
${JSON.stringify(chunk)}
<execution_protocol>
**CRITICAL INSTRUCTIONS**:
1. **EVIDENCE FIRST**: Every finding MUST cite a file and line number.
2. **TOOL ORDER**:
- Search First (get lineHint)
- Then LSP (use lineHint)
- Then Read (confirm text)
3. **OUTPUT FORMAT**: You MUST write to ${CONTEXT_DIR}/research-results/partial-research-${index}.json in the EXACT JSON schema defined.
</execution_protocol>
Write your findings to: ${CONTEXT_DIR}/research-results/partial-research-${index}.json
`
}))
results = Task_Parallel(parallel_tasks)
// Aggregate results from all parallel researchers
all_findings = []
total_answered = 0
total_partial = 0
total_not_found = 0
results.forEach((res, index) => {
try {
// Read the partial results file written by each researcher
partial_file = Read(CONTEXT_DIR + `/research-results/partial-research-${index}.json`)
partial_data = JSON.parse(partial_file)
// Merge findings into aggregate
if (partial_data.findings && Array.isArray(partial_data.findings)) {
partial_data.findings.forEach(finding => {
all_findings.push(finding)
// Track status counts
if (finding.status === "answered") total_answered++
else if (finding.status === "partial") total_partial++
else if (finding.status === "not_found") total_not_found++
})
}
} catch (error) {
WARN: `Failed to parse partial-research-${index}.json: ${error.message}`
}
})
// Validate we got findings
if (all_findings.length === 0):
ERROR: "Researcher agents failed to produce any findings"
update_state({
phase: "research-failed",
errors: [{
phase: "researcher",
message: "No findings produced by any researcher agent",
timestamp: new Date().toISOString(),
recoverable: true
}]
})
DISPLAY: "❌ Researcher Agent [Failed - No findings]"
EXIT code 1
// Write merged research.json (matching research-schema.json)
Write(CONTEXT_DIR + "/research.json", JSON.stringify({
metadata: {
version: "3.0",
generated_at: new Date().toISOString(),
agent: "researcher",
total_questions_researched: all_findings.length
},
findings: all_findings
}, null, 2))
// Success
update_state({
phase: "research-complete",
completed_agents: ["discovery-analysis", "engineer-questions", "researcher"],
current_agent: null
})
DISPLAY: "✅ Researcher Agent [Complete]"
DISPLAY: ` Questions researched: ${all_findings.length}`
DISPLAY: ` Answered: ${total_answered}, Partial: ${total_partial}, Not Found: ${total_not_found}`
DISPLAY: ""
```
