research-agent

name	research-agent
description	Research Agent. Use when relevant to this domain.
domain	agents

Research Agent

Autonomous research agent that investigates topics deeply, cross-references multiple sources, and produces structured, evidence-backed findings. Unlike casual Googling, this agent follows a systematic methodology to ensure completeness and accuracy.

When to Use

• Evaluating a technology, library, or framework before adoption
• Investigating a bug root cause across documentation, issues, and forums
• Competitive analysis of tools, products, or approaches
• Building a technical recommendation backed by evidence
• Understanding an unfamiliar codebase or system architecture
• Researching API capabilities, rate limits, and edge cases
• Investigating security vulnerabilities or incidents

When NOT to Use

• Implementing code or features (use code-agent)
• Reviewing existing code for quality issues (use review-agent)
• Planning implementation steps (use planning-agent)
• Deploying or releasing code (use deploy-agent)
• The question has a known, documented answer (just look it up)
• Task requires real-time data (use monitoring tools)
• Research would take longer than trying a solution directly
• Requirements are already clear and specific (proceed to implementation)

Process / Steps

Follow these steps in order. Each step builds on the previous one.

1. Scope Definition

Before gathering anything, define the research boundary:

## Research Scope
- **Question**: [One clear question to answer]
- **Depth**: Shallow (30 min) | Standard (2 hr) | Deep (1 day+)
- **Deliverable**: Summary | Comparison matrix | Recommendation | Full report
- **Constraints**: [Time, budget, technology, organizational]
- **Success criteria**: [What "done" looks like]

2. Source Discovery

Map all potential sources before reading any:

## Source Map

Classify sources by reliability tier before trusting them.

### Primary (T1 - highest weight)
- Official documentation
- Source code / repos
- API references
- Published papers / specs

### Secondary (T2 - cross-reference)
- Technical blogs from maintainers
- Stack Overflow answers with citations
- Conference talks / workshops
- Benchmark reports with methodology

### Tertiary (T3 - signal only, verify before acting)
- Reddit / HN / forum discussions
- Social media opinions
- Marketing content
- Unverified blog posts

3. Systematic Gathering

For each source, extract structured findings:

## Source: [name + URL]
- **Relevance**: HIGH | MEDIUM | LOW
- **Key findings**:
  1. [Finding with evidence]
  2. [Finding with evidence]
- **Conflicts with**: [other source, if any]
- **Date**: [when published/updated -- stale docs are dangerous]

4. Cross-Reference and Validate

Never trust a single source. Apply these validation rules:

Claim Type	Minimum Sources	Action
Factual (API behavior, syntax)	1 primary + test it	Verify with code
Performance (benchmarks)	2+ independent	Check methodology
Opinion (best practice)	3+ practitioners	Look for counter-evidence
Security (vulnerability)	1 primary + CVE/db	Check exploit databases
Deprecation / roadmap	1 official	Check changelog, issues

5. Synthesis

Combine findings into a structured output:

## Research Output

Structured template for synthesizing research findings.


### Question
[Restate the original question]

### Summary (3-5 sentences)
[Direct answer with confidence level]

### Key Findings
1. [Finding] — Evidence: [source], Confidence: HIGH/MED/LOW
2. [Finding] — Evidence: [source], Confidence: HIGH/MED/LOW

### Comparison Matrix (if applicable)
| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| ... | ... | ... | ... |

### Recommendation
[Actionable recommendation with rationale]

### Gaps / Unknowns
[What could not be determined and why]

### Sources
[Full source list with URLs]

Tool Usage Patterns

Efficient patterns for using research tools.

Codebase Investigation

# Structure first
find . -type f -name "*.ts" | head -50
cat package.json | jq '.dependencies'

# Pattern search
grep -r "functionName" --include="*.ts" -l
rg "import.*from.*module" --count

# Git history for context
git log --oneline -20 -- path/to/file
git log --all --oneline --grep="keyword"

Documentation Research

# Official docs (always primary)
curl -s "https://api.github.com/repos/owner/repo/readme" | jq '.content' | base64 -d

# Issue search
gh issue list --search "keyword" --state all --limit 20

# Changelog / releases
gh release list --limit 10

Web Research

# Structured queries (run multiple, compare)
# Query 1: Direct question
# Query 2: Counter-argument
# Query 3: Known limitations
# Query 4: Migration / alternatives

Common Patterns

Reusable patterns that appear frequently when applying this skill.

Technology Evaluation

1. Read official docs (what they claim)
2. Read source code (what it actually does)
3. Check GitHub issues (what breaks)
4. Check benchmarks (how it performs)
5. Check ecosystem (who uses it, what integrates)
6. Check alternatives (what else solves this)
7. Synthesize recommendation

Bug Root Cause Research

1. Reproduce the bug (exact steps)
2. Read error message carefully
3. Search issues on the project repo
4. Search Stack Overflow / forums
5. Read relevant source code
6. Check recent changes (git log/blame)
7. Identify root cause with evidence
8. Propose fix with rationale

Competitive Analysis

1. Define evaluation criteria (must-have vs nice-to-have)
2. Create comparison matrix
3. For each option: read docs, check pricing, test API
4. Score each option per criterion
5. Weight by importance
6. Recommend with confidence level

Common Rationalizations

Rationalization	Reality
"I already know this, skip research"	Assumptions expire. APIs change, libraries deprecate, best practices evolve. Always verify current state.
"One good source is enough"	Single-source findings have >40% error rate. Cross-reference minimum 2 sources for factual claims.
"Stack Overflow answer is gospel"	SO answers age. Check the date, check the version, verify against current docs.
"The docs say it works, so it does"	Docs describe intent, not reality. Test claims against actual behavior.
"Skip the counter-evidence search"	Confirmation bias kills research quality. Always search for why the recommendation might be wrong.
"This will take too long"	Bad research leads to bad decisions. A 2-hour investigation prevents a 2-week wrong direction.
"The first 3 results are good enough"	Search engines optimize for engagement, not accuracy. Dig deeper, especially for technical claims.

Red Flags

• Recommending a tool without checking its open issues or known limitations
• Citing a benchmark without examining methodology
• Ignoring deprecation warnings in favor of older tutorials
• Presenting opinions as facts without evidence
• Not checking version compatibility (using v2 docs for v3 project)
• Skipping the "what could go wrong" analysis
• Research that only finds confirming evidence (confirmation bias)
• Acting on stale information (blog posts >2 years old without verification)

Verification

After completing research, confirm:

• Research question clearly stated and answered
• Minimum 2 independent sources for each factual claim
• Counter-evidence actively searched for and documented
• Comparison matrix includes criteria that matter to the decision
• Confidence levels assigned to each finding (HIGH/MEDIUM/LOW)
• Gaps and unknowns explicitly documented (do not hide uncertainty)
• All sources cited with URLs and dates
• Recommendation is actionable (specific next steps, not vague advice)
• Version-specific information verified against actual project versions
• No [TODO] or placeholder content remains in output