Researcher Role Skill

Prerequisites

• Clear research question or problem statement
• Access to project context (DEVELOPMENT_PLAN, ARCHITECTURE)
• Internet access for external research
• Stakeholder requirements and constraints

Workflow

Phase 1: Technology Evaluation

Research and compare technology options for informed decision-making.

Step 1.1: Research Request Analysis

Load context files:
- DEVELOPMENT_PLAN.md (overall plan)
- ARCHITECTURE.md (current system)
- TODO.md (pending work)
- User request or issue description

Step 1.2: Define Research Scope

Create RESEARCH_BRIEF.md:

# Research Brief: [Topic]

## Research Question
[Clear, focused question to answer]

## Context
- Current state: [What exists now]
- Problem: [What needs solving]
- Constraints: [Technical, budget, timeline limitations]
- Success criteria: [What makes a solution acceptable]

## Research Scope
**In Scope**:
- [Specific area 1]
- [Specific area 2]

**Out of Scope**:
- [What we're NOT investigating]

## Stakeholders
- Requestor: [Name/Role]
- Decision makers: [Names/Roles]
- Implementation team: [Names/Roles]

## Timeline
- Research deadline: [Date]
- Decision deadline: [Date]
- Implementation target: [Date]

## Deliverables
- [ ] Technology comparison matrix
- [ ] Proof of concept (if needed)
- [ ] Implementation plan
- [ ] Risk assessment
- [ ] Final recommendation

Step 1.3: Conduct Research

Information Sources

1. Official Documentation

   • Read official docs, guides, API references
   • Check version compatibility and support lifecycle
   • Review migration guides and breaking changes

2. Community Resources

   • GitHub repositories (stars, issues, PR activity)
   • Stack Overflow discussions and common problems
   • Reddit, HackerNews, dev.to community sentiment
   • Conference talks and technical blog posts

3. Benchmarks and Performance

   • Published benchmarks and performance studies
   • Real-world case studies
   • Load testing results

4. Security and Compliance

   • CVE databases for known vulnerabilities
   • Security audit reports
   • Compliance certifications
   • License compatibility

Research Template

## Technology: [Name]

### Overview
- **Purpose**: [What it does]
- **Current Version**: [X.Y.Z]
- **Release Date**: [Date]
- **License**: [Type]
- **Maintainer**: [Organization/Individual]

### Key Features
- Feature 1: [Description]
- Feature 2: [Description]
- Feature 3: [Description]

### Pros
- ✅ [Advantage 1 with evidence]
- ✅ [Advantage 2 with evidence]
- ✅ [Advantage 3 with evidence]

### Cons
- ❌ [Disadvantage 1 with evidence]
- ❌ [Disadvantage 2 with evidence]
- ❌ [Disadvantage 3 with evidence]

### Performance
- Benchmark: [Metric with source]
- Scalability: [Evidence]
- Resource usage: [Data]

### Community & Support
- GitHub stars: [Count]
- Contributors: [Count]
- Open issues: [Count]
- Recent activity: [Assessment]
- Stack Overflow questions: [Count]
- Community size: [Assessment]

### Security
- Known vulnerabilities: [Count/Details]
- Security track record: [Assessment]
- Last security audit: [Date]

### Integration & Compatibility
- Works with: [List compatible technologies]
- Conflicts with: [List incompatibilities]
- Migration path from current: [Assessment]

### Learning Curve
- Documentation quality: [Rating/Assessment]
- Onboarding time: [Estimate]
- Team expertise: [Current level]
- Training resources: [Availability]

### Cost Analysis
- Licensing: [Free/Paid details]
- Infrastructure costs: [Estimates]
- Maintenance costs: [Estimates]
- Training costs: [Estimates]
- **Total Cost of Ownership**: [Estimate]

### Sources
1. [Source 1 with URL]
2. [Source 2 with URL]
3. [Source 3 with URL]

Step 1.4: Comparative Analysis

Create comparison matrix:

# Technology Comparison: [Use Case]

## Evaluation Criteria

| Criterion | Weight | Option A | Option B | Option C |
|-----------|--------|----------|----------|----------|
| Performance | 25% | 8/10 | 9/10 | 7/10 |
| Ease of Use | 20% | 7/10 | 6/10 | 9/10 |
| Community Support | 15% | 9/10 | 7/10 | 6/10 |
| Security | 20% | 8/10 | 9/10 | 7/10 |
| Cost | 10% | 6/10 | 8/10 | 9/10 |
| Integration | 10% | 7/10 | 8/10 | 6/10 |
| **Weighted Score** | | **7.7** | **8.0** | **7.4** |

## Detailed Comparison

### Performance
**Winner**: Option B
- Option A: [Specific performance metrics]
- Option B: [Specific performance metrics] ✅
- Option C: [Specific performance metrics]

**Evidence**: [Benchmark sources and data]

### Ease of Use
**Winner**: Option C
- Option A: [Developer experience assessment]
- Option B: [Developer experience assessment]
- Option C: [Developer experience assessment] ✅

**Evidence**: [Developer surveys, documentation quality]

[Continue for each criterion...]

## Risk Assessment

### Option A Risks
- **High**: [Risk with mitigation]
- **Medium**: [Risk with mitigation]
- **Low**: [Risk with mitigation]

### Option B Risks
- **High**: [Risk with mitigation]
- **Medium**: [Risk with mitigation]
- **Low**: [Risk with mitigation]

### Option C Risks
- **High**: [Risk with mitigation]
- **Medium**: [Risk with mitigation]
- **Low**: [Risk with mitigation]

Step 1.5: Proof of Concept (if needed)

# Proof of Concept: [Technology]

## Objective
Validate [specific capability] in our environment

## Approach
1. Setup: [Steps to configure]
2. Implementation: [What we built]
3. Testing: [How we validated]
4. Measurement: [Metrics collected]

## Results

### Success Criteria
- [Criterion 1]: ✅ PASSED / ❌ FAILED
- [Criterion 2]: ✅ PASSED / ❌ FAILED
- [Criterion 3]: ✅ PASSED / ❌ FAILED

### Performance Data
| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Response time | <100ms | 85ms | ✅ |
| Throughput | >1000 rps | 1200 rps | ✅ |
| Error rate | <0.1% | 0.05% | ✅ |

### Observations
- [Finding 1]
- [Finding 2]
- [Finding 3]

### Code Sample
```javascript
// POC implementation snippet
[Relevant code demonstrating key concepts]

Challenges Encountered

1. [Challenge and resolution]
2. [Challenge and resolution]

Conclusion

[Assessment of POC results]

**Step 1.6: Final Recommendation Report**

Create `RESEARCH_REPORT_[Topic].md`:

```markdown
# Research Report: [Topic]

**Date**: [YYYY-MM-DD]
**Researcher**: Researcher Agent
**Stakeholders**: [Names]
**Status**: Final / Draft

---

## Executive Summary

[2-3 paragraph summary covering:
- Research question
- Methodology
- Key findings
- Primary recommendation
- Expected impact]

---

## Research Context

### Background
[What prompted this research]

### Current State
[Description of existing solution/approach]

### Problem Statement
[What needs to be solved or improved]

### Constraints
- **Technical**: [Limitations]
- **Budget**: [Financial constraints]
- **Timeline**: [Time constraints]
- **Team**: [Skill/resource constraints]

---

## Research Methodology

### Approach
[How research was conducted]

### Sources Consulted
1. [Source type 1]: [Count] sources
2. [Source type 2]: [Count] sources
3. [Source type 3]: [Count] sources

### Evaluation Criteria
[How options were assessed]

---

## Findings

### Options Evaluated
1. **Option A - [Name]**
   - Summary: [Brief description]
   - Score: [X/10]
   - Best for: [Use case]

2. **Option B - [Name]**
   - Summary: [Brief description]
   - Score: [X/10]
   - Best for: [Use case]

3. **Option C - [Name]**
   - Summary: [Brief description]
   - Score: [X/10]
   - Best for: [Use case]

### Key Insights
1. [Insight with supporting evidence]
2. [Insight with supporting evidence]
3. [Insight with supporting evidence]

### Industry Trends
[Relevant trends and their implications]

---

## Recommendation

### Primary Recommendation
**Recommended Solution**: [Option Name]

**Justification**:
1. [Reason 1 with evidence]
2. [Reason 2 with evidence]
3. [Reason 3 with evidence]

**Expected Benefits**:
- [Benefit 1 with quantification if possible]
- [Benefit 2 with quantification if possible]
- [Benefit 3 with quantification if possible]

**Known Limitations**:
- [Limitation 1 and mitigation]
- [Limitation 2 and mitigation]

### Alternative Recommendation
**If primary recommendation is not feasible**: [Option Name]

**When to consider**: [Circumstances]

---

## Implementation Considerations

### Technical Requirements
- Infrastructure: [What's needed]
- Dependencies: [Required packages/services]
- Integration points: [How it connects]

### Resource Requirements
- Development time: [Estimate]
- Team members: [Count and roles]
- Budget: [Estimate]
- Training: [Time and resources]

### Timeline
**Phase 1**: [Duration] - [Activities]
**Phase 2**: [Duration] - [Activities]
**Phase 3**: [Duration] - [Activities]

**Total Timeline**: [Duration]

### Risk Analysis

| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
| [Risk 2] | High/Med/Low | High/Med/Low | [Strategy] |
| [Risk 3] | High/Med/Low | High/Med/Low | [Strategy] |

---

## Success Metrics

### Key Performance Indicators
1. **[Metric 1]**: [Baseline] → [Target]
2. **[Metric 2]**: [Baseline] → [Target]
3. **[Metric 3]**: [Baseline] → [Target]

### Measurement Plan
- Baseline measurement: [When and how]
- Progress tracking: [Frequency and method]
- Success evaluation: [Timeline and criteria]

---

## Next Steps

### Immediate Actions
1. [Action item] - Owner: [Role], Deadline: [Date]
2. [Action item] - Owner: [Role], Deadline: [Date]
3. [Action item] - Owner: [Role], Deadline: [Date]

### Decision Required
- **Decision maker**: [Name/Role]
- **Decision deadline**: [Date]
- **Decision criteria**: [What needs to be determined]

### Handoff
**To Architect** (or use architect-role-skill): [If architecture planning needed]
**To Builder** (or use builder-role-skill): [If prototyping needed]
**To DevOps** (or use devops-role-skill): [If infrastructure assessment needed]

---

## Appendices

### Appendix A: Detailed Comparison Matrix
[Comprehensive comparison table]

### Appendix B: Benchmark Data
[Detailed performance data]

### Appendix C: Security Analysis
[Security findings and assessments]

### Appendix D: Cost Breakdown
[Detailed cost analysis]

### Appendix E: References
1. [Source 1 with full citation]
2. [Source 2 with full citation]
3. [Source 3 with full citation]
[Continue numbering...]

---

**Document Version**: 1.0
**Last Updated**: [Date]
**Approved By**: [Name/Role] (if applicable)

Phase 2: Feature Research

Research and validate new feature proposals.

Step 2.1: Understand Feature Request

• What problem does it solve?
• Who are the users?
• What's the expected behavior?
• Any existing similar features in competitors?

Step 2.2: Research Similar Implementations

• How do competitors implement this?
• What are common patterns?
• What are common pitfalls?

Step 2.3: Analyze Technical Feasibility

• Compatible with current architecture?
• Required dependencies?
• Performance implications?
• Security considerations?

Step 2.4: Estimate Complexity

• Development effort
• Testing requirements
• Documentation needs
• Maintenance burden

Step 2.5: Create Feature Recommendation

# Feature Research: [Feature Name]

## Feature Description
[What the feature does]

## User Value
- **User Story**: As a [role], I want [feature] so that [benefit]
- **Expected Impact**: [Quantified benefit]
- **User Demand**: [Evidence of need]

## Technical Analysis

### Implementation Approach
[Recommended technical approach]

### Integration Points
[How it fits into existing system]

### Dependencies
- New: [What needs to be added]
- Modified: [What needs to change]

### Complexity Assessment
- **Complexity**: High / Medium / Low
- **Estimated Effort**: [Hours/Days/Weeks]
- **Risk Level**: High / Medium / Low

## Competitive Analysis
| Competitor | Implementation | UX Quality | Notes |
|------------|---------------|------------|-------|
| [Name] | [Approach] | [Rating] | [Observations] |

## Recommendation
**Recommendation**: Implement / Defer / Reject

**Rationale**: [Reasoning]

**Priority**: High / Medium / Low

**Suggested Timeline**: [When to implement]

Phase 3: Problem Investigation

Deep-dive into technical challenges and root cause analysis.

Step 3.1: Gather Information

• Error logs and stack traces
• System metrics and monitoring data
• User reports and reproduction steps
• Code history and recent changes

Step 3.2: Investigate Root Cause

• Review similar issues in community
• Analyze codebase for patterns
• Test hypotheses systematically
• Document findings

Step 3.3: Research Solutions

• Known fixes for similar issues
• Best practices for prevention
• Vendor documentation
• Expert recommendations

Step 3.4: Create Investigation Report

# Problem Investigation: [Issue Summary]

## Problem Description
[What's broken and how it manifests]

## Impact Assessment
- **Severity**: Critical / High / Medium / Low
- **Affected Users**: [Count/Percentage]
- **Business Impact**: [Description]
- **Urgency**: [Timeline for fix]

## Investigation Timeline
- Reported: [Date/Time]
- Investigation started: [Date/Time]
- Root cause identified: [Date/Time]
- Solution proposed: [Date/Time]

## Root Cause Analysis

### Symptoms
1. [Observable symptom]
2. [Observable symptom]

### Investigation Steps
1. [What was checked] → [Finding]
2. [What was checked] → [Finding]
3. [What was checked] → [Finding]

### Root Cause
[Detailed explanation of underlying cause]

### Contributing Factors
- [Factor 1]
- [Factor 2]

## Proposed Solutions

### Option 1: [Approach]
- **Description**: [How it fixes the problem]
- **Pros**: [Advantages]
- **Cons**: [Disadvantages]
- **Effort**: [Estimate]
- **Risk**: [Assessment]

### Option 2: [Approach]
[Same structure as Option 1]

### Recommended Solution
[Choice with justification]

## Prevention

### Immediate Actions
[Quick fixes to prevent recurrence]

### Long-term Improvements
[Systemic changes to address root cause]

### Monitoring
[How to detect similar issues early]

## References
[Sources consulted during investigation]

Research Quality Standards

Source Evaluation

• Credibility: Official docs > peer-reviewed > blog posts > forums
• Recency: Prefer recent sources (within 1-2 years)
• Relevance: Directly applicable to our use case
• Independence: Consider potential bias

Evidence Requirements

• Quantitative data when possible
• Multiple independent sources
• Real-world case studies
• Reproducible results

Citation Standards

• Always cite sources with URLs
• Include access dates
• Note if source is paywalled
• Archive important sources

Objectivity

• Present multiple perspectives
• Acknowledge limitations
• Avoid confirmation bias
• Separate facts from opinions

Collaboration Patterns

With Architect (or architect-role-skill)

• Provide research for architecture decisions
• Validate technical feasibility
• Supply competitive analysis

With Builder (or builder-role-skill)

• Share implementation examples
• Provide best practices
• Research specific technical questions

With Validator (or validator-role-skill)

• Research testing strategies
• Identify common edge cases
• Find security vulnerabilities

With DevOps (or devops-role-skill)

• Research infrastructure options
• Compare deployment strategies
• Analyze monitoring solutions

Examples

Example 1: Technology Comparison

Task: Evaluate state management libraries for React application

## Options Evaluated
- Redux Toolkit (Score: 8.2/10)
- Zustand (Score: 8.5/10)
- Jotai (Score: 7.8/10)

## Recommendation
**Selected**: Zustand

**Justification**:
- Simpler API than Redux (30% less boilerplate)
- Better TypeScript support
- Similar performance to Redux
- Easier learning curve for team

**Result**: Decision made within 2 days of research

Example 2: Feature Feasibility

Task: Research real-time collaboration feature

## Feature Analysis
- Complexity: High (WebSocket implementation required)
- Dependencies: Socket.io, Redis for pub/sub
- Estimated effort: 3-4 weeks
- Competitive analysis: 3 of 5 competitors have similar feature

## Recommendation
**Recommendation**: Implement (Phase 2)

**Priority**: Medium

**Justification**: High user demand, competitive advantage, manageable complexity

**Result**: Greenlit for implementation in Q2

Example 3: Problem Investigation

Task: Investigate intermittent database connection failures

## Root Cause
Connection pool exhaustion due to missing `finally` blocks in async operations

## Evidence
- 15 instances of unclosed connections found
- Correlation between failures and high traffic periods
- Similar issue reported in library GitHub issues

## Solution
- Add `finally` blocks to all database operations
- Implement connection pool monitoring
- Set up alerts for pool utilization >80%

**Result**: Issue resolved, no recurrence in 30 days

Resources

Templates

• resources/RESEARCH_BRIEF_template.md - Research scope template
• resources/RESEARCH_REPORT_template.md - Final report template
• resources/TECHNOLOGY_EVALUATION_template.md - Tech comparison template
• resources/FEATURE_RESEARCH_template.md - Feature analysis template

Research Tools

• GitHub API for repository metrics
• npm/PyPI for package statistics
• Stack Overflow for community sentiment
• CVE databases for security information

References

• Agent Skills vs. Multi-Agent
• Research Methodology Best Practices
• Technology Evaluation Frameworks

Version: 1.0.0 Last Updated: December 12, 2025 Status: ✅ Active Maintained By: Claude Command and Control Project