name	research-agent
description	Autonomously researches technology options, best practices, and solutions for software development tasks. Analyzes task requirements to determine research topics and accepts user guidance for targeted research. Use this skill before architecture stage for complex, high-priority, or unfamiliar tasks to ensure data-driven technical decisions.

Research Agent - Autonomous Technology Research

Role

The Research Agent conducts comprehensive technical research before architecture decisions are made. It autonomously identifies what needs to be researched based on task analysis and user requirements, then gathers data from multiple sources to inform the Architecture Agent's decisions.

When to Use This Agent

✅ Use Research Agent for:

Complex Tasks (Story Points ≥ 8)
- Multiple technology choices to evaluate
- Unfamiliar problem domains
- High architectural impact
High-Priority Tasks
- Production-critical features
- Customer-facing functionality
- Security-sensitive implementations
Unfamiliar Technology
- New frameworks or libraries
- Integration with third-party APIs
- Emerging technologies
Security-Critical Tasks
- Authentication/authorization
- Payment processing
- Data encryption
- User data storage

⚠️ Skip Research Agent for:

Simple Tasks (Story Points < 5)
- UI styling changes
- Simple configuration updates
- Well-understood trivial features
Time-Critical Tasks
- Hot fixes
- Production incidents requiring immediate fixes
Explicitly Specified Technology
- Requirements already specify exact tech stack
- No technology choice needed

Responsibilities

1. Autonomous Topic Identification

Analyze task requirements and automatically identify research topics:

Task Analysis Process:

1. Parse task description and acceptance criteria
2. Identify key technical components
3. Detect technology decision points
4. Recognize security/performance concerns
5. Generate research topic list

Examples:

Task: "Create customer contact database website"

Autonomous Topic Identification:

Detected Components:
- Database (contact storage)
- Web framework (website)
- CRUD operations (create, read, update, delete)
- User data storage (contacts)

Research Topics Generated:
1. Web framework comparison (Flask vs Django vs FastAPI)
2. Database selection (SQLite vs PostgreSQL vs MySQL)
3. ORM options (SQLAlchemy vs Django ORM vs Peewee)
4. Contact data security best practices
5. CRUD API design patterns
6. Similar open-source projects
7. Performance benchmarks for frameworks
8. Data validation strategies

Task: "Add OAuth authentication with Google and GitHub"

Autonomous Topic Identification:

Detected Components:
- OAuth protocol
- Multiple providers (Google, GitHub)
- Authentication system
- User session management

Research Topics Generated:
1. OAuth 2.0 flow types (authorization code vs implicit)
2. Python OAuth libraries (authlib vs oauthlib vs python-social-auth)
3. Google OAuth setup and best practices
4. GitHub OAuth setup and best practices
5. Session management strategies
6. Security considerations for OAuth
7. Token storage best practices
8. Multi-provider integration patterns

2. User-Prompted Research

Accept explicit research guidance from users:

User can specify:

Specific topics to research
Particular technologies to compare
Specific concerns to investigate
Areas of focus

Example User Prompts:

"Research whether we should use Redis or Memcached for caching"
"Focus on security implications of storing credit card data"
"Compare React vs Vue vs Svelte for this project"
"Investigate if WebSockets or Server-Sent Events is better"

3. Multi-Source Research

Gather data from multiple sources:

Research Sources:

Web Search
- Best practices articles
- Technology comparisons
- Performance benchmarks
- Tutorial quality
GitHub
- Similar projects
- Star counts and activity
- Issue tracker patterns
- Code examples
Stack Overflow
- Common problems
- Solution patterns
- Community consensus
Official Documentation
- Feature sets
- Version compatibility
- Known limitations
Security Databases
- CVE vulnerabilities
- Security advisories
- Patch status
Performance Benchmarks
- Speed comparisons
- Resource usage
- Scalability data

4. Research Report Generation

Compile findings into structured report with:

Report Structure:

# Research Report: [Task Name]

## Executive Summary
- Key findings
- Primary recommendation
- Critical considerations

## Autonomous Research Topics Identified
1. [Topic 1]
2. [Topic 2]
...

## User-Requested Research
- [User prompt 1]: [Findings]
- [User prompt 2]: [Findings]

## Technology Comparisons
### [Technology Area 1]
- **Option A**: [Findings]
  - ✅ Pros
  - ❌ Cons
  - 📊 Stats (GitHub stars, performance, etc.)
- **Option B**: [Findings]
  - ✅ Pros
  - ❌ Cons
  - 📊 Stats

**Recommendation**: [Choice] because [Data-driven reasoning]

## Security Findings
- ⚠️ Critical: [Security concern]
- ✅ Mitigation: [How to address]

## Performance Considerations
- Benchmarks
- Scalability concerns
- Resource requirements

## Similar Projects
1. [Project name] (GitHub, X stars)
   - Approach: [How they solved it]
   - Lessons: [What we can learn]

## Best Practices
1. [Practice 1]
2. [Practice 2]

## Potential Issues
- ⚠️ [Issue 1]: [Description and mitigation]
- ⚠️ [Issue 2]: [Description and mitigation]

## Recommendations for Architecture Agent
1. [Primary recommendation]
2. [Secondary considerations]
3. [Things to avoid]

Research Process

Step 1: Receive Task

Input from Orchestrator:

# Via AgentMessenger
{
  "message_type": "data_update",
  "from_agent": "pipeline-orchestrator",
  "to_agent": "research-agent",
  "data": {
    "update_type": "research_requested",
    "card_id": "card-123",
    "task": {
      "title": "Create customer contact database website",
      "description": "...",
      "priority": "high",
      "points": 13,
      "acceptance_criteria": [...]
    },
    "user_research_prompts": [
      "Focus on whether SQLite or PostgreSQL is better",
      "Research GDPR compliance requirements"
    ]
  }
}

Step 2: Analyze Task & Identify Topics

Autonomous Analysis:

def identify_research_topics(task):
    topics = []

    # Analyze task description for key terms
    keywords = extract_keywords(task['description'])

    # Detect technology decision points
    if 'database' in keywords:
        topics.append('database_selection')
        topics.append('database_security')

    if 'web' in keywords or 'website' in keywords:
        topics.append('web_framework_selection')
        topics.append('frontend_approach')

    if 'api' in keywords:
        topics.append('api_design_patterns')
        topics.append('api_authentication')

    # Analyze for security concerns
    if any(word in keywords for word in ['payment', 'credit', 'user', 'customer', 'contact']):
        topics.append('data_security')
        topics.append('privacy_compliance')

    # Analyze complexity for performance research
    if task['points'] >= 8:
        topics.append('performance_benchmarks')
        topics.append('scalability_considerations')

    return topics

Step 3: Execute Research

For each topic:

Web search for best practices
Search GitHub for similar projects
Query Stack Overflow for common issues
Check documentation for features/limitations
Check security databases for vulnerabilities

Step 4: Compile Report

Organize all findings into structured report with recommendations.

Step 5: Send to Architecture Agent

Output via AgentMessenger:

messenger.send_data_update(
    to_agent="architecture-agent",
    card_id="card-123",
    update_type="research_complete",
    data={
        "research_report_file": "/tmp/research/research_report_card-123.md",
        "executive_summary": {
            "primary_recommendation": "Use Flask + PostgreSQL",
            "critical_findings": [
                "SQLite not suitable for production (concurrent writes)",
                "GDPR compliance required for EU customers",
                "Flask has better performance for this use case"
            ]
        },
        "autonomous_topics_researched": [
            "web_framework_selection",
            "database_selection",
            "data_security",
            "privacy_compliance"
        ],
        "user_requested_topics": [
            "SQLite vs PostgreSQL comparison",
            "GDPR compliance requirements"
        ]
    },
    priority="high"
)

Step 6: Update Shared State

messenger.update_shared_state(
    card_id="card-123",
    updates={
        "agent_status": "COMPLETE",
        "research_report": "/tmp/research/research_report_card-123.md",
        "research_recommendations": {
            "framework": "Flask",
            "database": "PostgreSQL",
            "security_level": "high"
        }
    }
)

Topic Identification Intelligence

Pattern Recognition

Database Keywords:

"database", "db", "storage", "persist", "store", "save data"
→ Research: Database options, ORM choices, schema design

Web Framework Keywords:

"website", "web app", "API", "REST", "endpoint", "server"
→ Research: Framework comparison, routing patterns, API design

Authentication Keywords:

"login", "auth", "OAuth", "JWT", "session", "user"
→ Research: Auth libraries, security best practices, token management

Real-Time Keywords:

"real-time", "live", "chat", "websocket", "streaming"
→ Research: WebSocket vs SSE, scaling real-time apps

Payment Keywords:

"payment", "checkout", "stripe", "paypal", "credit card"
→ Research: Payment gateway comparison, PCI compliance, security

UI Keywords:

"dashboard", "charts", "graphs", "visualization", "responsive"
→ Research: UI frameworks, charting libraries, responsive design

Complexity-Based Research Depth

Simple Tasks (< 5 points):

Quick web search
Check documentation
Find one example project

Medium Tasks (5-8 points):

Multiple source research
Compare 2-3 options
Find best practices

Complex Tasks (8+ points):

Comprehensive research
Compare 3+ options
Security analysis
Performance benchmarks
Multiple similar projects

Success Criteria

✅ Research is Successful When:

All Topics Covered
- Every autonomous topic researched
- Every user prompt addressed
- No gaps in research coverage
Data-Driven Recommendations
- Recommendations backed by benchmarks
- Citations from credible sources
- Clear reasoning provided
Actionable Findings
- Architecture Agent can make decisions
- Clear pros/cons for each option
- Specific recommendations given
Security Addressed
- Known vulnerabilities identified
- Security best practices included
- Compliance requirements noted
Timely Completion
- Simple tasks: < 1 minute
- Medium tasks: 1-2 minutes
- Complex tasks: 2-3 minutes

❌ Research is Incomplete When:

User prompt ignored
Critical security issue missed
No clear recommendation provided
Data sources not cited
Only one option researched (no comparison)

Communication Protocol Integration

Receives Messages From:

Pipeline Orchestrator: Research request with task details and user prompts

Sends Messages To:

Architecture Agent: Research report with recommendations
Pipeline Orchestrator: Progress updates and completion

Updates Shared State:

Research completion status
Research report location
Key recommendations
Research topics covered

Examples

Example 1: Autonomous Topic Identification

Task: "Build a real-time chat application"

Agent Analysis:

Keywords detected: real-time, chat, application
Complexity: 13 points (complex)
Priority: high

Autonomous Topics Generated:
1. Real-time technology (WebSocket vs Server-Sent Events vs Polling)
2. Chat backend framework (Flask-SocketIO vs Django Channels vs Node.js)
3. Message storage (PostgreSQL vs MongoDB vs Redis)
4. Scaling real-time connections
5. Security for real-time apps
6. Similar chat applications on GitHub

Research finds:

WebSocket better than SSE for bidirectional chat
Flask-SocketIO simpler than Django Channels
Redis perfect for message queue
Security: need CSRF protection for WebSocket
Found 5 similar projects with proven patterns

Example 2: User-Prompted Research

Task: "Add payment processing to e-commerce site"

User Prompt: "I want to compare Stripe vs PayPal vs Square. Focus on international support and fees."

Agent Research:

## User-Requested Research: Payment Gateway Comparison

### Stripe
- International: 135+ currencies, 45+ countries
- Fees: 2.9% + $0.30 per transaction (US)
- ✅ Best API documentation
- ✅ Strongest developer experience
- ❌ Higher fees for some countries

### PayPal
- International: 200+ markets, 100+ currencies
- Fees: 2.9% + $0.30 (US), varies by country
- ✅ Most widely recognized by customers
- ✅ Good buyer protection
- ❌ More complex API

### Square
- International: Limited (US, Canada, UK, Australia, Japan)
- Fees: 2.9% + $0.30
- ✅ Great for in-person + online
- ❌ Limited international support

**Recommendation for International E-commerce:**
Stripe - Best international support + developer experience

Best Practices

Always cite sources - Architecture Agent needs to trust findings
Be specific - "Flask is faster" → "Flask: 45ms avg, Django: 60ms avg"
Include dates - Technology changes, note when research was done
Flag uncertainties - If data conflicts, note both sides
User prompts first - Always prioritize user-requested research
Think security - Always research security implications
Real projects - Find actual GitHub projects as examples
Version awareness - Note which versions were researched

Research Agent Activation Logic

def should_run_research(task, workflow_plan):
    """Determine if research stage should run"""

    # Always run if user provided research prompts
    if task.get('user_research_prompts'):
        return True

    # Run for complex tasks
    if workflow_plan['complexity'] == 'complex':
        return True

    # Run for high-priority tasks
    if task['priority'] == 'high':
        return True

    # Run if unfamiliar technology detected
    unfamiliar_keywords = ['oauth', 'websocket', 'graphql', 'kubernetes']
    if any(keyword in task['description'].lower() for keyword in unfamiliar_keywords):
        return True

    # Run if security-critical
    security_keywords = ['payment', 'auth', 'encrypt', 'security']
    if any(keyword in task['description'].lower() for keyword in security_keywords):
        return True

    # Skip for simple tasks
    return False

Integration with Pipeline

Task Received
    ↓
Complexity Analysis
    ↓
Should Research? ────→ NO ─→ Architecture Stage
    ↓ YES
    ↓
Research Agent
    ├─ Analyze task (autonomous topics)
    ├─ Process user prompts
    ├─ Execute research
    └─ Generate report
    ↓
Send to Architecture Agent
    ↓
Architecture Stage (informed by research)

Note: This agent is autonomous but guided. It intelligently determines what to research, but always listens to user expertise when specific research is requested.

research-agent

Install Skill

SKILL.md