external research

External Research Skill

Overview

This skill defines the mandatory methodology for conducting external research during planning and implementation phases. It ensures that all external knowledge is gathered from authoritative sources, properly validated, version-aware, and correctly cited.

Why External Research is Critical

The Problem with Model Memory

Large Language Models have knowledge cutoffs and can hallucinate API details, deprecated patterns, or incorrect version-specific behavior. Relying solely on model memory for technical implementation details is dangerous and unacceptable.

Common failure modes when relying on model memory:

Failure Mode	Example	Consequence
Outdated APIs	Using componentWillMount in React 18	Runtime warnings, deprecated code
Version Mismatches	Assuming FastAPI 0.100+ syntax in 0.95 project	Import errors, crashes
Hallucinated Methods	Inventing .toJSON() on objects that don't have it	Runtime errors
Security Vulnerabilities	Using outdated authentication patterns	Exploitable code
Incorrect Defaults	Wrong default parameter values	Subtle bugs
Missing Breaking Changes	Not knowing about API removals	Production failures

The Solution: Verified External Research

By using external research tools, we:

1. Get current, accurate information directly from official sources
2. Verify version compatibility before writing any code
3. Discover breaking changes that model memory doesn't know about
4. Find security advisories and best practices
5. Locate working code examples from official documentation
6. Ensure correct API signatures with proper types and parameters

---

Research Capabilities

Your environment likely provides these capabilities (tool names vary by platform):

1. Web Search (e.g., search_web, @web, /web)

Purpose: Discover official documentation, changelogs, breaking changes, security advisories, RFCs, tutorials, and best practices.

When to Use:

• Starting research on any external library or framework
• Finding official documentation URLs
• Discovering recent changes, updates, or deprecations
• Locating security advisories or CVEs
• Finding community best practices and patterns
• Researching error messages or edge cases

Best Practices:

• Use specific, targeted queries (e.g., "FastAPI 0.110 authentication JWT" not just "FastAPI auth")
• Include version numbers when relevant
• Include the current year to filter out outdated content (see Time-Aware Searching below)
• Search for "[library] breaking changes [version]" when upgrading
• Search for "[library] security advisory" for security-sensitive code
• Use the domain parameter to prioritize official sources (e.g., domain: "fastapi.tiangolo.com")

⏰ Time-Aware Searching (Critical for Relevant Results):

Adding the current year dramatically improves search result relevance:

# Without year - may return outdated 2020-2023 content
"FastAPI JWT authentication"

# With year - prioritizes current best practices
"FastAPI JWT authentication 2026"
"React useEffect best practices 2026"
"Python security vulnerabilities 2026"

Why this matters:

• Libraries update frequently; old tutorials may use deprecated APIs
• Security recommendations evolve constantly
• LLM training data has cutoffs; searching with current year compensates
• Use the script scripts/get_current_time.py --tips for query examples

Query Examples:

Good: "Next.js 14 app router server actions tutorial 2026"
Good: "React 18 useEffect cleanup async 2026"
Good: "Python 3.12 new features type hints"
Bad:  "how to use react"
Bad:  "javascript tutorial"

---

2. URL Fetching (e.g., read_url_content, WebFetch, URL Context)

Purpose: Fetch and read the actual content of documentation pages, specifications, guides, and reference materials discovered via search_web.

When to Use:

• After discovering relevant URLs via search_web
• Reading official API reference documentation
• Extracting code examples from documentation
• Validating that a URL contains the information you need
• Reading changelogs and migration guides
• Extracting specific parameter details, types, and signatures

Best Practices:

• Always read official documentation, not just search snippets
• Extract and note exact API signatures, not paraphrased versions
• Look for code examples you can adapt
• Note any warnings, caveats, or edge cases mentioned
• Check the documentation version matches your target version
• Read multiple sections if needed (installation, usage, API reference)

What to Extract:

• Exact function/method signatures with types
• Required vs optional parameters
• Default values
• Return types
• Exception/error types that can be raised
• Code examples (especially official ones)
• Version-specific notes or warnings

---

3. Documentation APIs (e.g., context7 MCP, library-specific APIs)

Purpose: Deep, version-aware framework, SDK, and API knowledge with authoritative context. Provides structured documentation queries with version-specific accuracy.

Tools Available:

• mcp_context7_resolve-library-id: Resolves a library name to a Context7-compatible ID
• mcp_context7_query-docs: Queries documentation for a specific library

When to Use:

• When you need version-specific API details
• For deep framework knowledge (React, Next.js, FastAPI, etc.)
• When you need accurate, structured API information
• To verify patterns and best practices for specific versions
• When search_web results are too general or scattered

Best Practices:

1. Always resolve the library ID first using mcp_context7_resolve-library-id
2. Use specific, detailed queries (not just "how to use X")
3. Include context about what you're trying to accomplish
4. Reference the version you're targeting
5. Use the returned code examples as authoritative references

Query Examples:

Good: "How to implement JWT authentication middleware in Express.js 4.x"
Good: "React 18 useEffect cleanup function for async operations"
Good: "FastAPI dependency injection with database sessions"
Bad:  "auth"
Bad:  "database"

Library ID Format: /org/project or /org/project/version Examples:

• /vercel/next.js
• /fastapi/fastapi
• /facebook/react
• /expressjs/express

---

Research Methodology

Step 1: Identify What Needs Research

Before writing any code that uses external libraries, APIs, or frameworks, identify:

• All external libraries/packages being used
• The exact versions of each library
• Specific features or APIs you'll be using
• Any integrations between libraries
• Security-sensitive operations (auth, crypto, etc.)

Step 2: Conduct Systematic Research

For each external dependency:

1. Resolve library ID (if using context7)

   mcp_context7_resolve-library-id("fastapi", "How to create API endpoints with authentication")
   

2. Query official documentation

   mcp_context7_query-docs("/fastapi/fastapi", "JWT authentication with OAuth2PasswordBearer")
   

3. Search for additional context

   search_web("FastAPI 0.110 JWT authentication best practices", domain: "fastapi.tiangolo.com")
   

4. Read and validate documentation

   read_url_content("https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/")
   

Step 3: Document Your Findings

All research must be documented with:

• Source URL with section anchors where possible
• Version number the documentation applies to
• Key findings relevant to your implementation
• Code examples extracted from official sources
• Warnings/caveats mentioned in the documentation

---

What You MUST NOT Rely on Model Memory For

❗ NEVER assume model memory is accurate for:

Category	Why It's Dangerous
Library APIs	Methods may be renamed, deprecated, or removed between versions
Function Signatures	Parameter names, types, and defaults change frequently
Version Compatibility	What works in v2.0 may not exist in v1.5
Security Practices	Security recommendations evolve; old patterns become vulnerabilities
Framework Behavior	Internal behavior changes even when APIs look the same
Default Values	Defaults can change between versions, causing subtle bugs
Error Handling	Exception types and error formats change
Configuration Options	Config keys are added, renamed, or removed
Environment Variables	Expected env vars change between versions
Database Schemas	ORM/database patterns evolve significantly

---

Research Validation Checklist

Before considering research complete, verify:

Discovery Validation

• All external APIs and libraries were discovered using search_web
• Official documentation URLs were located
• Version-specific documentation was identified

Content Validation

• All referenced documentation pages were read using read_url_content
• API signatures were extracted accurately (not paraphrased)
• Code examples were found and noted

Framework Validation

• Framework or SDK behavior was validated using context7 MCP where applicable
• Version-specific patterns were confirmed
• Any framework-specific gotchas were identified

Accuracy Validation

• Version numbers are explicitly stated for all dependencies
• No undocumented or assumed behavior exists in the plan
• All external knowledge has a citation
• Security implications were researched if applicable

---

Citation Format

All externally sourced knowledge MUST be cited in your plan or documentation.

Standard Citation Format

### Relevant Documentation

- [FastAPI Security - OAuth2 with JWT](https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/)
  - Version: FastAPI 0.110+
  - Key Content: OAuth2PasswordBearer implementation pattern
  - Why Needed: Required for implementing secure token authentication
  - Sourced via: search_web → read_url_content

- [React useEffect Reference](https://react.dev/reference/react/useEffect)
  - Version: React 18.2
  - Key Content: Cleanup function patterns for async operations
  - Why Needed: Prevent memory leaks in component unmount
  - Sourced via: context7 MCP

Version Context

Always include explicit version numbers:

✅ Good: "FastAPI v0.110 OAuth2PasswordBearer"
✅ Good: "React 18.2 useEffect cleanup"
✅ Good: "Next.js 14.1 App Router server actions"

❌ Bad: "FastAPI authentication"
❌ Bad: "React hooks"
❌ Bad: "Next.js routing"

---

Common Research Scenarios

Scenario 1: Implementing a New Feature with External Library

1. Search for official documentation: search_web("[library] official docs")
2. Resolve library ID: mcp_context7_resolve-library-id("[library]", "[your goal]")
3. Query specific feature: mcp_context7_query-docs("[library-id]", "[specific feature]")
4. Read installation/setup guide: read_url_content("[docs-url]/getting-started")
5. Read API reference for your use case: read_url_content("[docs-url]/api/[feature]")

Scenario 2: Upgrading a Dependency

1. Search for changelog: search_web("[library] changelog [version]")
2. Search for breaking changes: search_web("[library] breaking changes [old-version] to [new-version]")
3. Search for migration guide: search_web("[library] migration guide [version]")
4. Read migration documentation: read_url_content("[migration-guide-url]")

Scenario 3: Security-Sensitive Code

1. Search for security best practices: search_web("[library] security best practices [year]")
2. Search for security advisories: search_web("[library] CVE security advisory")
3. Query secure patterns: mcp_context7_query-docs("[library-id]", "security authentication encryption")
4. Read security section of docs: read_url_content("[docs-url]/security")

Scenario 4: Debugging/Error Research

1. Search for the specific error: search_web("[exact error message]")
2. Search for common causes: search_web("[library] [error type] common causes")
3. Read GitHub issues if relevant: read_url_content("[github-issue-url]")
4. Query documentation: mcp_context7_query-docs("[library-id]", "[error context]")

---

Integration with Planning Phase

When using this skill during the planning phase (e.g., with the plan-feature workflow):

1. Phase 3 of planning should leverage all three tools
2. All documentation links in the plan should be sourced via these tools
3. No API details should be assumed—they must be verified
4. The implementation plan should include citations for all external knowledge
5. Validation commands should include research validation as Level 0

Example Phase 3 Integration

### Phase 3: External Research & Documentation

> 📚 **Using External Research Skill**

**Research Conducted:**

1. **context7 MCP**: Queried `/vercel/next.js` for "App Router authentication patterns"
2. **search_web**: Searched "Next.js 14 middleware authentication JWT"
3. **read_url_content**: Read https://nextjs.org/docs/app/building-your-application/authentication

**Findings:**
- Next.js 14 uses middleware.ts for route protection
- JWT validation should happen in middleware, not in page components
- Server actions can access session via cookies() helper

**Citations:**
- [Next.js Authentication Docs](https://nextjs.org/docs/app/building-your-application/authentication) - v14.1

---

Quality Assurance

Signs of Good Research

✅ Specific version numbers mentioned ✅ Direct links to official documentation ✅ Exact API signatures extracted (not paraphrased) ✅ Code examples from official sources ✅ Warnings and caveats noted ✅ Multiple sources cross-referenced ✅ Clear citation trail (which tool found what)

Signs of Inadequate Research

❌ Vague statements like "according to the docs" ❌ No version numbers specified ❌ Paraphrased API signatures ❌ No direct documentation links ❌ Assumed behavior without verification ❌ Single source only ❌ No code examples referenced

---

Summary

External research is not optional—it is a mandatory requirement for producing reliable, maintainable, and secure code. The three tools (search_web, read_url_content, context7 MCP) work together to provide:

1. Discovery (search_web) → Find where information lives
2. Validation (read_url_content) → Read and extract actual content
3. Deep Context (context7 MCP) → Get version-specific, structured knowledge

Always research. Always cite. Always verify. Never assume.