Research Docs

Documentation Research Skill

Research coding documentation efficiently using Perplexity AI and persist findings in a structured, AI-optimized format.

Core Principles

1. Check Existing Research First - Always read research/CLAUDE.md (memory index) to see if topic was researched before
2. Structured Persistence - Save all research to research/<topic>.md with consistent formatting
3. AI-Optimized Output - Use clear sections, code examples, and structured data
4. Documentation Focus - Prioritize official docs, GitHub repos, and authoritative sources
5. Memory-Based Index - research/CLAUDE.md is a Claude Code memory file that auto-loads to provide research context

research/CLAUDE.md Format

The research/CLAUDE.md file is a Claude Code memory file that follows these best practices:

Memory Best Practices (from Claude Code documentation):

• ✓ Be specific: "Use 2-space indentation" not "Format code properly"
• ✓ Use structure: Format as bullet points under descriptive headings
• ✓ Stay scannable: Clear sections, consistent formatting
• ✓ Review periodically: Update as research evolves

Index Entry Format:

### <Topic Name> (`<topic>.md`)

**Researched:** YYYY-MM-DD
**Status:** Active | Deprecated | Updated
**When to Use:** Specific concrete scenarios (be detailed)
**Summary:**
- Specific actionable point 1
- Specific actionable point 2
- Specific actionable point 3

This format ensures:

• Claude can quickly scan for relevant research
• Entries are specific and actionable
• Research context loads automatically in every session
• Index serves as a memory aid across sessions

Workflow

Step 1: Check Existing Research

ALWAYS start by checking if we've researched this topic before:

# Read the research index
cat research/CLAUDE.md

Look for the topic in the research index. If found, read the existing research file:

cat research/<topic>.md

If the research exists and is recent (< 3 months old), use it. Otherwise, proceed to Step 2.

Step 2: Identify Research Topic

Determine the specific topic to research. Create a clean topic name:

• Use lowercase with hyphens
• Be specific but concise
• Examples: python-asyncio, react-hooks, typescript-generics, docker-best-practices

Step 3: Execute Perplexity Search

Use the optimized research script with appropriate parameters:

# Basic documentation research
.claude/skills/research-docs/scripts/perplexity-research.sh "python asyncio best practices"

# Target specific domains
.claude/skills/research-docs/scripts/perplexity-research.sh -d "docs.python.org,realpython.com" "python async await"

# Recent documentation only
.claude/skills/research-docs/scripts/perplexity-research.sh -r month "react 19 new features"

# More comprehensive results
.claude/skills/research-docs/scripts/perplexity-research.sh -n 20 "rust ownership patterns"

Script Options:

• -n, --max-results NUM: Number of results (1-20, default: 15)
• -r, --recency FILTER: day, week, month, year (default: year)
• -d, --domains LIST: Comma-separated domain list
• -f, --format FORMAT: structured (default), json, plain

Step 4: Create Structured Documentation

Save the research output to research/<topic>.md using this format:

# <Topic Name>

**Research Date:** YYYY-MM-DD
**Status:** Active | Deprecated | Updated
**Related Topics:** topic1, topic2, topic3

## Overview

Brief 2-3 sentence overview of the topic.

## Key Concepts

- **Concept 1**: Explanation
- **Concept 2**: Explanation
- **Concept 3**: Explanation

## Official Documentation

- [Primary Docs](<url>) - Description
- [API Reference](<url>) - Description

## Best Practices

### Do's

- ✓ Practice 1 with brief explanation
- ✓ Practice 2 with brief explanation

### Don'ts

- ✗ Anti-pattern 1 with brief explanation
- ✗ Anti-pattern 2 with brief explanation

## Common Patterns

### Pattern 1: <Name>

**Use Case:** When to use this pattern

**Example:**
```language
// Code example

Explanation: Why this works

Pattern 2:

Use Case: When to use this pattern

Example:

// Code example

Explanation: Why this works

Common Pitfalls

Pitfall 1:

Problem: Description of the issue

Solution:

// Correct approach

Pitfall 2:

Problem: Description of the issue

Solution:

// Correct approach

Integration Examples

Basic Setup

// Installation or basic setup

Advanced Usage

// More complex example

Version Information

• Current Stable: Version number
• Minimum Required: Version number
• Deprecated Features: List any deprecated features

Related Resources

• Resource 1 - Description
• Resource 2 - Description

Research Sources

Last Updated: YYYY-MM-DD Next Review: YYYY-MM-DD (3 months from research date)

### Step 5: Update research/CLAUDE.md Index

**ALWAYS update research/CLAUDE.md** with an entry for the research.

The `research/CLAUDE.md` file is a **memory file** that Claude Code automatically loads. It serves as an index of all researched topics.

**Format Guidelines** (following Claude Code memory best practices):
- ✓ **Be specific**: Include concrete details, not vague descriptions
- ✓ **Use structure**: Format as bullet points under descriptive headings
- ✓ **Stay scannable**: Use clear sections and consistent formatting
- ✓ **Update regularly**: Keep status and dates current

Add a new entry under the "Research Index" heading:

```markdown
### <Topic Name> (`<topic>.md`)

**Researched:** YYYY-MM-DD
**Status:** Active
**When to Use:** Specific scenarios where this applies (be concrete)
**Summary:**
- Key point 1 with specific detail
- Key point 2 with specific detail
- Key point 3 with specific detail

Example entry:

### Python Asyncio (`python-asyncio.md`)

**Researched:** 2025-11-18
**Status:** Active
**When to Use:** Building concurrent I/O-bound applications, async web servers, or async database operations
**Summary:**
- Use `asyncio.create_task()` for fire-and-forget, `asyncio.gather()` for concurrent execution with results
- Always use `async with` for async context managers to ensure proper cleanup
- Avoid blocking calls in async functions - use `asyncio.to_thread()` for CPU-bound work

Step 6: Create TODO List

Use the TodoWrite tool to track research progress:

[
  {"content": "Check existing research in research/CLAUDE.md", "status": "completed", "activeForm": "Checking existing research"},
  {"content": "Execute Perplexity search for <topic>", "status": "completed", "activeForm": "Executing Perplexity search"},
  {"content": "Structure documentation in research/<topic>.md", "status": "in_progress", "activeForm": "Structuring documentation"},
  {"content": "Update research/CLAUDE.md research index", "status": "pending", "activeForm": "Updating research/CLAUDE.md research index"}
]

Documentation Categories

Framework Documentation

• React, Vue, Angular, Svelte
• Next.js, Nuxt, SvelteKit
• Express, FastAPI, Django

Language Documentation

• Python, JavaScript/TypeScript, Rust, Go
• Java, Kotlin, Swift
• Ruby, PHP, C#

Tool Documentation

• Docker, Kubernetes
• Git, GitHub Actions
• Webpack, Vite, esbuild

API Documentation

• REST API design
• GraphQL
• WebSockets

Best Practices

• Code patterns
• Architecture patterns
• Security practices
• Performance optimization

Output Quality Standards

Must Include

• ✓ Clear, scannable structure
• ✓ Code examples for key concepts
• ✓ Links to official documentation
• ✓ Best practices and anti-patterns
• ✓ Version information
• ✓ Common pitfalls and solutions

Avoid

• ✗ Large blocks of unformatted text
• ✗ Outdated information without version context
• ✗ Examples without explanation
• ✗ Missing links to sources
• ✗ Vague or generic advice

Example Queries That Trigger This Skill

• "Research Python asyncio documentation"
• "Find best practices for React hooks"
• "Look up TypeScript generics documentation"
• "What are the latest Docker best practices?"
• "Research how to implement WebSockets in Node.js"
• "Find documentation on Rust error handling"
• "Look up GraphQL schema design patterns"

Maintenance

Updating Existing Research

When updating research:

1. Read the existing file
2. Add a note at the top: **Updated:** YYYY-MM-DD - Reason for update
3. Update the "Last Updated" date
4. Update the "Next Review" date
5. Update the research/CLAUDE.md entry with new date

Deprecation

If documentation becomes outdated:

1. Update status to "Deprecated"
2. Add deprecation notice with replacement topic
3. Update research/CLAUDE.md status

Troubleshooting

Perplexity API Errors

Error: API key invalid

• Check PERPLEXITY_API_KEY environment variable
• Ensure you have a new API key that supports Search API

Error: Rate limit exceeded

• Wait before making additional requests
• Consider reducing result count with -n flag

Research Quality Issues

Too many irrelevant results

• Use domain filtering: -d "official-docs.com,github.com"
• Make query more specific
• Adjust recency filter: -r month

Missing official documentation

• Explicitly include official domain in search query
• Use -d flag to target specific authoritative sources

Best Practices

1. Always check existing research first - Avoid duplicate work
2. Use specific queries - "Python 3.12 asyncio patterns" vs "Python async"
3. Target authoritative sources - Use domain filtering for official docs
4. Structure consistently - Follow the documentation template
5. Include examples - Code examples make documentation actionable
6. Update research/CLAUDE.md - Keep the research index current
7. Set review dates - Mark when research should be refreshed
8. Track with TODOs - Use TodoWrite to show progress

Script Reference

The perplexity-research.sh script is located at:

.claude/skills/research-docs/scripts/perplexity-research.sh

Key Features:

• Pre-configured for documentation domains
• AI-optimized structured output
• Flexible filtering options
• Error handling and validation
• Multiple output formats

Default Documentation Domains:

• stackoverflow.com
• github.com
• docs.python.org
• developer.mozilla.org
• nodejs.org
• reactjs.org
• vuejs.org
• angular.io
• rust-lang.org
• go.dev
• kotlinlang.org
• dev.to
• medium.com

Override with -d flag for specific research needs.