Research Information Lookup

Overview

This skill provides multi-provider research lookup with intelligent routing between:

Gemini Deep Research: 60-minute comprehensive research with extensive citations (requires GEMINI_API_KEY + pay-as-you-go API)
Perplexity Sonar: Fast web-grounded research in 30 seconds (requires OPENROUTER_API_KEY)

The skill automatically selects the best provider and model based on:

Research mode configuration (balanced, perplexity, deep_research, auto)
Query complexity (keywords, length, structure)
Context (planning phase, task type)

Research Modes

Mode	Provider Selection	Best For	Total Plan Time
`balanced`	Deep Research for Phase 1 analysis, Perplexity for others	Most projects (recommended)	~90 min
`perplexity`	Always use Perplexity	Quick planning, well-known tech	~30 min
`deep_research`	Always use Gemini Deep Research	Novel domains, high-stakes	~4 hours
`auto`	Automatic based on keywords/context	Let the system decide	Varies

Deep Research Budget Constraints

CRITICAL: You have a strict budget of 2 Deep Research queries per /full-plan session.

Budget Allocation Strategy

Deep Research is expensive (30-60 min per query, high API cost). Use it ONLY for:

Phase 1: Competitive Landscape/Analysis (Highest Priority)
- Comprehensive market analysis with multiple competitors
- Industry trends and adoption patterns
- Regulatory landscape with complex timelines
Phase 2: Novel Architecture Decisions (Use Sparingly)
- ONLY if technology stack is highly uncertain or cutting-edge
- DEFAULT to Gemini Pro or Perplexity for standard tech stack research

DO NOT Use Deep Research For:

Version checks or feature comparisons (use Perplexity)
Pricing lookups or cost estimates (use Perplexity)
Quick technical documentation (use Perplexity)
Simple "what is X" queries (use Gemini Flash/Perplexity)
Phases 3-6 research (use Perplexity - better temporal accuracy)

Budget Tracking

The system automatically tracks usage in planning_outputs/<project>/DEEP_RESEARCH_BUDGET.json. Falls back to Gemini Pro if budget exhausted.

Before using Deep Research, ask: Is this critical to project viability? Does it require 30-60 min multi-source analysis? Can Perplexity provide sufficient depth?

Remember: Perplexity has better temporal accuracy for 2026 data, so prefer it for time-sensitive queries even in Phase 1.

When to Use This Skill

Current Research Information: Latest studies, papers, and findings
Literature Verification: Check facts, statistics, or claims
Background Research: Context and supporting evidence for planning
Citation Sources: Find relevant papers and studies to cite
Technical Documentation: Specifications, protocols, methodologies
Recent Developments: Emerging trends and breakthroughs
Statistical Data: Survey results, research findings

Visual Enhancement with Project Diagrams

When creating documents with this skill, always consider adding diagrams to enhance visual communication.

Use the project-diagrams skill for system architecture, data flow, integration workflow, and process pipeline diagrams:

python .claude/skills/project-diagrams/scripts/generate_schematic.py "your diagram description" -o figures/output.png

Usage

Command-Line Interface

# Basic usage with auto mode (context-aware selection)
python research_lookup.py "Your research query here"

# Specify research mode explicitly
python research_lookup.py "Competitive landscape for SaaS market" \
  --research-mode deep_research

# Provide context for smart routing
python research_lookup.py "Latest PostgreSQL features" \
  --research-mode balanced \
  --phase 2 \
  --task-type architecture-research

# Force specific Perplexity model
python research_lookup.py "Quick fact check" \
  --research-mode perplexity \
  --force-model pro

# Save output to file / JSON format
python research_lookup.py "your query" -o results.txt
python research_lookup.py "your query" --json -o results.json

API Requirements

For Perplexity (required for perplexity and balanced modes):

export OPENROUTER_API_KEY='your_openrouter_key'

For Gemini Deep Research (required for deep_research and balanced modes):

export GEMINI_API_KEY='your_gemini_key'
# Requires pay-as-you-go API ($19.99/month)

Progress Tracking & Monitoring (v1.4.0+)

For long-running Deep Research operations (60+ minutes), comprehensive progress tracking and checkpoint capabilities are available.

Monitor Active Research

# List all active research operations
python scripts/monitor-research-progress.py <project_folder> --list

# Monitor specific operation with live updates
python scripts/monitor-research-progress.py <project_folder> <task_id> --follow

Resume Interrupted Research

If Deep Research is interrupted (network issues, timeout), resume from checkpoints:

# List resumable tasks with time estimates
python scripts/resume-research.py <project_folder> 1 --list

# Resume from checkpoint (saves up to 50 minutes)
python scripts/resume-research.py <project_folder> 1 --task <task_name>

Checkpoint Strategy: 15% (~9 min saved), 30% (~18 min saved), 50% (~30 min saved).

Key Features: Automatic checkpoints at milestones, graceful degradation (Deep Research to Perplexity fallback), error recovery with exponential backoff, external monitoring support.

See Also: docs/WORKFLOWS.md, scripts/enhanced_research_integration.py, scripts/resumable_research.py

Automatic Model Selection

Model Types

Model	Use Case	Context	Pricing	Speed
Sonar Pro (`perplexity/sonar-pro`)	Straightforward lookup	200K tokens	$3/1M prompt + $15/1M completion + $5/1K searches	Fast (5-15s)
Sonar Reasoning Pro (`perplexity/sonar-reasoning-pro`)	Complex analytical queries	128K tokens	$2/1M prompt + $8/1M completion + $5/1K searches	Slower (15-45s)

Complexity Assessment

Reasoning Keywords (triggers Sonar Reasoning Pro):

Analytical: compare, contrast, analyze, evaluate, critique
Comparative: versus, vs, compared to, differences between
Synthesis: meta-analysis, systematic review, synthesis
Causal: mechanism, why, how does, explain, relationship
Debate: controversy, conflicting, paradox, debate
Trade-offs: pros and cons, advantages and disadvantages, trade-off

Scoring: Reasoning keywords = 3 pts each; Multiple questions = 2 pts per ?; Complex clauses = 1.5 pts; Long queries (>150 chars) = 1 pt. Threshold: >= 3 pts triggers Reasoning Pro.

Example Classifications:

Sonar Pro Search (straightforward):

"Recent advances in CRISPR gene editing 2024"
"Prevalence of diabetes in US population"

Sonar Reasoning Pro (complex):

"Compare and contrast mRNA vaccines vs traditional vaccines for cancer treatment"
"Analyze the controversy surrounding AI in medical diagnosis and evaluate trade-offs"

Manual Override

python research_lookup.py "your query" --force-model pro       # Force Sonar Pro
python research_lookup.py "your query" --force-model reasoning  # Force Reasoning Pro

Query Best Practices

Structured Query Format

[Topic] + [Specific Aspect] + [Time Frame] + [Type of Information]

Good Queries:

"CRISPR gene editing + off-target effects + 2024 + clinical trials"
"Quantum computing + error correction + recent advances + review papers"
"Renewable energy + solar efficiency + 2023-2024 + statistical data"

Poor Queries: "Tell me about AI" (too broad), "Cancer research" (lacks specificity)

For detailed query examples, capability descriptions, and paper quality standards, see references/query_guide.md.

Integration with Project Planning

Technology Research: Current information on frameworks, tools, best practices
Architecture Validation: Verify patterns against current standards
Competitive Analysis: Compare solutions with similar projects
Decision Support: Inform architectural decisions with latest evidence
Cost Research: Pricing and service comparisons

Error Handling and Limitations

Known Limitations: Information cutoff, paywall content, very recent unindexed papers, proprietary databases.

Fallback Strategies: Rephrase queries, break complex queries into simpler components, use broader time frames, cross-reference with multiple variations.

For provider-specific technical details, API configuration, performance/cost considerations, and complementary tool guidance, see references/provider_details.md.

Summary

This skill serves as a powerful research assistant with intelligent dual-model selection:

Automatic Intelligence: Analyzes query complexity and selects the optimal model
Cost-Effective: Uses faster Sonar Pro Search for straightforward lookups
Deep Analysis: Engages Sonar Reasoning Pro for complex analytical queries
Flexible Control: Manual override available when needed
Academic Focus: Both models configured to prioritize peer-reviewed sources
Complementary WebSearch: Use alongside WebSearch for metadata verification and non-academic sources

research-lookup