Research

Comprehensive academic research using OpenAlex, Paper-search, PDF extraction, and web search (Tavily). Always produces 5+ evidence cards covering conflicting ideas with weighted evidence synthesis.

Quick Start

Decision Tree:

• Need evidence-based decision? → Use this skill
• Quick lookup only? → Use search skill instead
• Already researched topic? → Run ada::research:list

Core Workflow:

Step 0: Gather codebase context (ALWAYS FIRST)
Step 1: Formulate research question
Step 2: Comprehensive discovery (25+ sources)
Step 3: Create 5+ evidence cards incrementally
Critical Evaluation: Assess for codebase context
Step 4: Generate comprehensive report

Mandatory Requirements:

• ✅ Always 5+ evidence cards (broad coverage)
• ✅ Explicitly seek conflicting ideas
• ✅ Weight evidence (academic + real-world sources)
• ✅ Codebase context informs research question

CRITICAL: Write-First Pattern

MANDATORY: After 1-2 tool calls:

1. Write/update evidence card immediately
2. Update references.json immediately
3. SAVE files before next tool calls
4. CONTINUE research (writing ≠ stopping)

Why: Context windows are limited. Writing preserves knowledge even if context resets.

Failure Modes:

• ❌ 3+ tool calls before writing → context overload
• ❌ Stopping after one card → must continue until complete
• ❌ Not updating references.json → loses tracking

Workflow Summary

Step 0: Codebase Context (ALWAYS FIRST)

Search codebase for: architecture, patterns, technologies, existing implementations. Use context to inform research question.

Step 1: Research Question

1. Create .ada/data/research/{topic}/
2. Create research-question.md using template
3. Create references.json with intent

Step 2: Discovery (Target: 25+ Sources)

Academic (OpenAlex, Paper-search):

• Foundational: get_top_cited_works (min_citations: 50+)
• Recent SOTA: search_works (from_year: 2020+)
• Citation networks: get_citation_network

Non-Academic (Tavily via search skill):

• Blogs, docs, case studies in parallel
• Target: 5-10 relevant sources

Conflict-Seeking:

• "{approach A} vs {approach B}"
• "{approach} limitations"
• "alternative to {approach}"

Step 3: Evidence Cards (5+ Required)

1. Read 1-2 papers/sources
2. Create/update evidence card
3. Update references.json
4. SAVE files
5. REPEAT until 5+ cards

Grouping: Same approach → same card. Different approach → new card.

Critical Evaluation

After 5+ cards, before report:

1. Assess strengths/weaknesses
2. Evaluate for codebase context
3. Compare tradeoffs systematically
4. Identify best fit

Step 4: Research Report

1. Re-read all evidence cards: ada::research:show
2. Re-read research-question.md
3. Create research-report.md using template
4. Include "Answer to Original Question" section

Tools Quick Reference

Tool	Purpose	When
OpenAlex get_top_cited_works	Foundational papers	Discovery
OpenAlex search_works	Recent SOTA	Discovery
OpenAlex get_citation_network	Related work	Deep dive
Paper-search search_arxiv	Preprints	Recent work
PDF read_pdf	Extract content	Reading papers
Tavily (search skill)	Non-academic	Parallel discovery
zai-zread search_doc	Semantic issues/PRs/docs	Real-world implementations
webfetch	Direct URL reads	Lightweight docs/files
look_at	Interpret diagrams/images	PDFs/screenshots

Research Management Commands

ada::research:status              # Full status + next action
ada::research:status --next       # Just next action
ada::research:status --checkpoint # Verify state
ada::research:status --ref <name> # Load reference file

ada::research:list                # List all sessions
ada::research:show <session>      # Show evidence cards
ada::research:cleanup --all       # Clear PDFs

Load References On-Demand:

ada::research:status --ref workflow      # Workflow guide
ada::research:status --ref evidence-cards # Card guide
ada::research:status --ref template-card  # Card template
ada::research:status --ref weighting      # Weighting framework

Key Tips (Reminders)

Source Weighting

Type	Weight	Examples
Academic (50+ citations)	High	Peer-reviewed papers
Academic (10-50 citations)	Medium	Recent SOTA
Real-world case studies	High	Company post-mortems
Blogs, tutorials	Medium-Low	Expert content

Evidence Card Essentials

• Key claims with page number citations
• Assumptions and conditions
• Tradeoffs and limitations
• Related/conflicting approaches
• Implementation resources

Common Mistakes

• ❌ Reading 3+ papers before writing → Write after 1-2
• ❌ Not seeking conflicts → Explicitly search opposing views
• ❌ Skipping codebase context → Always start with Step 0
• ❌ Stopping at 3 cards → Must reach 5+ for broad coverage

Directory Structure

.ada/
├── data/research/{topic}/
│   ├── research-question.md
│   ├── evidence-card-*.md
│   ├── research-report.md
│   └── references.json
└── temp/research/downloads/  # Temporary PDFs

References

Templates:

• references/templates/template-research-question.md
• references/templates/template-evidence-card.md
• references/templates/template-research-report.md
• references/templates/template-references.json

Guides:

• references/guides/guide-workflow.md - Detailed workflows
• references/guides/guide-evidence-cards.md - Card creation
• references/guides/guide-weighting.md - Source weighting
• references/guides/guide-critical-evaluation.md - Evaluation framework
• references/guides/guide-reports.md - Report generation
• references/guides/guide-adaptive-strategies.md - Handling edge cases

Examples:

• references/examples/example-evidence-card.md
• references/examples/example-research-report.md
• references/examples/example-workflows.md

Reference:

• references/reference/reference-tools.md - Complete MCP documentation

Integration

• With search skill: Use Tavily in parallel for non-academic sources
• With docs-write: Use evidence cards for documentation decisions