research-retrieval

name: research-retrieval description: Search external documentation (web pages, API docs, papers) and generate useful summaries for development. Use when investigating new technologies, understanding third-party APIs, researching best practices, or gathering information for technical decisions. Reduces hallucinations and expands agent knowledge. license: MIT metadata: author: AC Framework version: "1.0"

Research & Retrieval

External knowledge search, documentation retrieval, and synthesis for informed development decisions.

When to Use This Skill

Use this skill when:

Investigating new technologies, libraries, or frameworks
Understanding third-party APIs and their capabilities
Researching best practices for a specific problem
Gathering information for architecture decisions
Need to verify facts or current information
Exploring solutions to unfamiliar problems

Instructions

Step 1: Define Research Goals

Clarify what you need to know:
- Specific technical question
- Comparison of technologies
- Implementation approach
- Best practices
Identify sources:
- Official documentation
- API references
- Technical blogs
- Research papers
- GitHub repositories
- Stack Overflow
Set scope boundaries:
- Time period (recent vs. historical)
- Version specificity
- Language/framework constraints

Step 2: Search and Retrieve

Official Documentation:

Priority sources:
1. Official docs (docs.{service}.com)
2. API reference
3. Getting started guides
4. Best practices
5. Changelog/release notes

Technical Blogs & Articles:

Quality indicators:
- Recent publication date
- Author expertise/credentials
- Code examples included
- Community engagement
- Updated for current versions

Research Papers (for advanced topics):

Use when:
- Novel algorithms needed
- Performance optimizations
- Academic foundations
- Cutting-edge techniques

GitHub Repositories:

Evaluate by:
- Stars/forks (popularity)
- Recent commits (maintenance)
- Issue resolution (support)
- Documentation quality
- Test coverage

Step 3: Evaluate Sources

Credibility Checklist:

Authoritative source (official > third-party)
Up-to-date information
Well-explained with examples
Community-validated (comments, issues)
Version compatibility noted

Red Flags:

Outdated documentation
Unexplained "magic" solutions
No code examples
Deprecated approaches
Unsupported claims

Step 4: Extract Key Information

For each relevant source, extract:

## Source: [Title/URL]

**Relevance**: [High/Medium/Low]
**Date**: [Publication date]
**Version**: [Software version, if applicable]

### Key Points

1. [Important finding 1]
2. [Important finding 2]
3. [Important finding 3]

### Code Examples

\`\`\`[language]
// Relevant code snippet
\`\`\`

### Warnings/Caveats

- [Known issues or limitations]
- [Breaking changes]
- [Performance considerations]

### References

- [Link 1]
- [Link 2]

Step 5: Synthesize Findings

Compare approaches:

## Technology Comparison: [Topic]

### Option A: [Technology A]

**Pros**:
- Advantage 1
- Advantage 2

**Cons**:
- Disadvantage 1
- Disadvantage 2

**Best for**: [Use cases]

### Option B: [Technology B]

**Pros**:
- Advantage 1
- Advantage 2

**Cons**:
- Disadvantage 1
- Disadvantage 2

**Best for**: [Use cases]

### Recommendation

[Your recommendation with justification]

Synthesize best practices:

## Best Practices: [Topic]

Based on [N] sources, consensus on:

### Do's
1. [Recommended approach 1]
2. [Recommended approach 2]

### Don'ts
1. [Anti-pattern 1]
2. [Anti-pattern 2]

### Trade-offs
- [Decision point]: [Option A] vs [Option B]
  - Choose A when: [conditions]
  - Choose B when: [conditions]

Step 6: Generate Actionable Steps

Convert research into implementation steps:

## Implementation Guide: [Topic]

### Prerequisites
- [Requirement 1]
- [Requirement 2]

### Step-by-Step

1. **Setup**
   - [Action 1]
   - [Action 2]

2. **Configuration**
   - [Action 3]
   - [Action 4]

3. **Implementation**
   - [Action 5]
   - [Action 6]

4. **Testing**
   - [Action 7]

### Common Pitfalls
- [Pitfall 1] → [Solution]
- [Pitfall 2] → [Solution]

Step 7: Store for Reuse

Save findings in references/ directory:

references/
├── README.md (index of all references)
├── api/
│   ├── stripe-api-2024-01.md
│   └── openai-api-best-practices.md
├── libraries/
│   ├── react-server-components.md
│   └── state-management-comparison.md
└── patterns/
    ├── authentication-patterns.md
    └── caching-strategies.md

Step 8: Link to OpenSpec

Reference research in specs:

## Specification: [Feature]

### Research References

- [Authentication Patterns](../references/patterns/authentication-patterns.md)
- [Stripe API Integration](../references/api/stripe-api-2024-01.md)

### Decisions Based on Research

1. **Use JWT for authentication**
   - Rationale: [Summary of research findings]
   - Sources: [Links to references]

2. **Implement Redis caching**
   - Rationale: [Performance benchmarks from research]
   - Sources: [Links to references]

Output Format

After research is complete:

## Research Summary: [Topic]

**Sources Consulted**: [N]
**Date**: [Research date]
**Confidence**: [High/Medium/Low]

### Executive Summary

[2-3 sentence overview of findings]

### Key Findings

1. [Finding 1 with source]
2. [Finding 2 with source]
3. [Finding 3 with source]

### Recommendations

1. [Actionable recommendation 1]
2. [Actionable recommendation 2]

### Implementation Steps

[Step-by-step guide based on research]

### References Stored

- references/[category]/[filename].md
- [Link to full research document]

### Uncertainties/Gaps

- [What still needs investigation]
- [Questions that remain unanswered]

Guardrails

Verify critical information - Cross-reference multiple sources
Check publication dates - Avoid outdated information
Prefer official docs - Authoritative over anecdotal
Acknowledge uncertainty - Be clear when information is incomplete
Document sources - Always cite where information came from
Focus on actionable info - Avoid research rabbit holes

Search Strategies

Error Messages:

"[exact error message]" + [technology name]

Feature Comparisons:

[technology A] vs [technology B] 2024
[technology A] alternative

Best Practices:

[technology] best practices
[technology] common pitfalls

Implementation Guides:

[technology] getting started tutorial
[technology] example project

Requirements

Web search capability
Access to documentation sites
Ability to evaluate source credibility
Understanding of the domain being researched