Research Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Research Skill facilitates comprehensive academic and web-based research to support evidence-based decision-making. It leverages tools like OpenAlex, PDF extraction, and web search to gather a wide range of sources. The primary output is a collection of at least five "evidence cards" that synthesize findings, cover conflicting ideas, and inform a final, comprehensive research report. This skill is triggered for tasks requiring deep technical investigation, literature reviews, or comparing architectural patterns.
The core philosophy is to transform information gathering into a systematic process of weighing ideas, understanding complex topics from multiple perspectives, and navigating tradeoffs to produce context-aware recommendations. This is crucial for making long-term architectural or technology decisions.
Sources: skills/research/SKILL.md:3-8, skills/research/references/guides/guide-decision-making.md:5-19
Core Workflow
The research process follows a structured, multi-step workflow designed to ensure relevance, comprehensiveness, and preservation of context. It begins with understanding the existing codebase and concludes with a detailed report that directly answers the initial research question.
Sources: skills/research/SKILL.md:16-23, skills/research/references/guides/guide-workflow.md:19-29
The following diagram illustrates the high-level research workflow.
Step 0: Gather Codebase Context
Before any research begins, the agent must search the codebase for existing architecture, patterns, and technologies related to the topic. This context is crucial for formulating a relevant and actionable research question.
Sources: skills/research/SKILL.md:33-35, skills/research/references/guides/guide-workflow.md:32-44
Step 1: Formulate Research Question
A research directory is created at .ada/data/research/{topic}/, and a research-question.md file is generated. This file documents the problem statement, desired outcome, and constraints, all informed by the codebase context gathered in Step 0.
Sources: skills/research/SKILL.md:37-40, skills/research/references/guides/guide-workflow.md:46-58
Step 2: Comprehensive Discovery
The goal is to find over 25 sources using a parallel, dual-source strategy.
- Academic Sources: Uses OpenAlex and Paper-search MCPs to find foundational (highly cited) and recent state-of-the-art papers.
- Non-Academic Sources: Uses the
searchskill (Tavily) to find blog posts, documentation, and case studies. - Conflict-Seeking: The process explicitly searches for conflicting ideas (e.g., "{approach A} vs {approach B}") and limitations to ensure a balanced perspective.
Sources: skills/research/SKILL.md:42-56, skills/research/references/guides/guide-workflow.md:60-96
Step 3: Incremental Evidence Card Creation
This step requires creating at least five evidence cards. Each card synthesizes information from one or two sources. This is governed by the mandatory "Write-First Pattern" to avoid context loss.
Sources: skills/research/SKILL.md:58-64, skills/research/references/guides/guide-workflow.md:98-151
Step 4: Generate Research Report
After a critical evaluation of all evidence, a final research-report.md is created. This report synthesizes all findings, compares the different approaches, discusses conflicts, and provides a direct answer to the original research question with recommendations.
Sources: skills/research/SKILL.md:71-75, skills/research/references/guides/guide-workflow.md:169-196
Write-First Pattern
To combat the limited context windows of AI models, the research skill enforces a mandatory "Write-First Pattern". After reading a maximum of one or two sources, the agent must immediately write or update an evidence card and save its state in references.json before proceeding. This ensures that knowledge is preserved incrementally.
Sources: skills/research/SKILL.md:25-31, skills/research/references/guides/guide-workflow.md:6-17
This sequence diagram shows the mandatory "Write-First" loop.
Architecture and Data
Directory Structure
All research artifacts for a given topic are stored in a dedicated directory within .ada/data/research/. This ensures that all evidence, reports, and metadata are co-located and organized.
Sources: skills/research/SKILL.md:104-111
The diagram below shows the directory structure for a research session.
Sources: skills/research/SKILL.md:105-111
Evidence Cards
Evidence cards are the core knowledge artifacts of the research process. Each card synthesizes findings from one or more sources about a specific approach. They are designed to be a persistent, re-readable store of knowledge.
Sources: skills/research/references/guides/guide-evidence-cards.md:3-10
| Component | Description |
|---|---|
| Key Claims | The main arguments or findings, with citations (e.g., page numbers). |
| Evidence | Direct quotes or data supporting the claims. |
| Assumptions | The underlying assumptions made by the source. |
| Tradeoffs/Limitations | The downsides or constraints of the approach. |
| Related Approaches | Links to other evidence cards, especially conflicting ones. |
| Implementation Resources | Links to libraries, code examples, or tutorials. |
Sources: skills/research/SKILL.md:98-102, skills/research/references/guides/guide-evidence-cards.md:12-45
Source Weighting
Evidence is not treated equally. The skill uses a weighting system to prioritize sources based on their type and authority. Academic papers with many citations are given high weight, while blog posts have lower but still valuable weight, especially for state-of-the-art topics.
Sources: skills/research/SKILL.md:91-97, skills/research/references/guides/guide-decision-making.md:30-35
| Source Type | Weight | Examples |
|---|---|---|
| Academic (50+ citations) | High | Peer-reviewed foundational papers |
| Real-world case studies | High | Company engineering blogs, post-mortems |
| Academic (10-50 citations) | Medium | Recent state-of-the-art papers |
| Blogs, tutorials | Medium-Low | Content from recognized experts |
Sources: skills/research/SKILL.md:92-97
Tools and Commands
The Research skill integrates several MCPs (Multi-Capability Providers) for discovery and content extraction, and provides a set of shell commands for managing the research lifecycle.
Sources: skills/research/SKILL.md:77-89, AGENTS.md:65-76
Integrated Tools (MCPs)
| Tool | Purpose | Provider |
|---|---|---|
get_top_cited_works | Find foundational academic papers. | openalex-research |
search_works | Find recent state-of-the-art papers. | openalex-research |
search_arxiv | Search for pre-print papers. | paper-search |
read_pdf | Extract text content from PDF files. | pdf-reader |
search (Tavily) | Search the web for non-academic sources. | tavily-remote-mcp |
search_doc | Perform semantic search on GitHub issues, PRs, and docs. | zai-zread |
Sources: skills/research/SKILL.md:78-89, AGENTS.md:65-76
Management Commands
A suite of bash scripts is available to manage and inspect research sessions.
| Command | Description |
|---|---|
ada::research:status | Shows the full status of the current research session and suggests the next action. |
ada::research:list | Lists all past and current research sessions. |
ada::research:show <session> | Displays all evidence cards for a given session. |
ada::research:cleanup --all | Clears temporary downloaded PDF files. |
ada::research:status --ref <name> | Loads a specific reference file (e.g., workflow, evidence-cards) into context. |
Sources: skills/research/SKILL.md:91-107
Summary
The Research Skill provides a robust and structured framework for conducting in-depth technical research. By enforcing a systematic workflow that includes codebase analysis, comprehensive discovery, and the mandatory "Write-First Pattern," it ensures that the generated insights are both thorough and directly applicable to the project's context. The emphasis on creating at least five evidence cards covering conflicting viewpoints and weighting sources allows the agent to make well-informed, evidence-based decisions, moving beyond simple information retrieval to genuine synthesis and analysis.
Sources: skills/research/SKILL.md, skills/research/references/guides/guide-workflow.md, skills/research/references/guides/guide-decision-making.md.