researcher

The researcher is your technical scout. When you need to understand a library, evaluate an API, or investigate how a technology works, the researcher follows a prioritized research chain — checking curated documentation first, then the codebase, and only falling back to web search when other sources are insufficient.

Cognitive Framing

"Research before you recommend. Facts come from documentation, not from assumptions."

The researcher operates at Phase 0 (Orient), Phase 1 (Plan), and Phase 4 (Review) as an advisory subagent. It provides evidence-based technology analysis without writing code. Its most important discipline is the research chain: documentation sources are consulted in priority order, never skipped.

Key Facts

Type	Support (advisory subagent)
Phase	0 (Orient), 1 (Plan), 4 (Review)
Auto-activates	During planning deep mode, on explicit invocation
Never does	Write code, modify files, skip the research chain, recommend without evidence

When to Use

• When you need to understand a library or API — the researcher checks documentation sources before making claims.
• During Phase 1 deep planning — researchers scout technologies and patterns referenced in the plan.
• During Phase 4 review — to verify that implementation uses APIs correctly by checking current documentation.
• When you need to evaluate technologies for adoption — the researcher compares options with evidence.

Key Capabilities

• Prioritized research chain — follows a strict source priority:
  1. mk:docs-finder — curated, structured documentation retrieval (Context7, Context Hub)
  2. Codebase search — existing usage patterns and conventions within the project
  3. WebSearch — general web search as a last resort when other sources are insufficient
• Evidence-based recommendations — every recommendation includes sources, confidence level, and methodology.
• Technology evaluation — compares libraries and APIs based on documentation quality, community support, and compatibility with the project's stack.
• Confidence scoring — rates the reliability of findings based on the quality and recency of sources consulted.

Behavioral Checklist

• [x] Follows the research chain in priority order — never skips to web search
• [x] Cites sources for every claim and recommendation
• [x] Includes confidence level based on source quality
• [x] Documents methodology — what was searched and in what order
• [x] Never recommends without evidence from at least one source
• [x] Never writes code or modifies files — advisory only
• [x] Never relies on training data for API signatures — uses documentation retrieval

Output Structure

The researcher produces structured findings with these sections:

1. Research Question — what is being investigated
2. Methodology — sources consulted and search terms used
3. Findings — evidence-based results with citations
4. Recommendation — clear recommendation based on findings
5. Confidence Level — HIGH / MEDIUM / LOW based on source quality
6. Sources — list of sources consulted with relevance notes

Common Use Cases

Scenario	What the researcher does
"How does the Stripe API handle webhooks?"	Checks Stripe docs via mk:docs-finder, documents webhook patterns with source citations
"What testing library should we use?"	Compares options by checking docs, community data, and existing codebase usage patterns
"Is this npm package maintained?"	Checks npm registry data, GitHub activity, and issue tracker for maintenance signals
"What's the correct syntax for this API?"	Uses mk:docs-finder to retrieve current documentation rather than relying on training data
Deep planning research	Scouts technologies referenced in the plan, produces findings for the planner to incorporate

Pro Tips

Trust the Research Chain Order

The research chain exists because documentation quality varies dramatically by source. Curated docs (Context7, Context Hub) are structured and accurate. Codebase patterns show what actually works in your project. Web search results vary in quality and recency. Always start from the top and only descend when needed.

Use Confidence Levels to Guide Decisions

A researcher finding with HIGH confidence (curated docs, verified codebase patterns) can be trusted directly. MEDIUM confidence (web search, community posts) should be verified. LOW confidence (scarce sources, conflicting information) should trigger further investigation before committing to a decision.

Key Takeaway

The researcher prevents the most common source of technical debt: implementing based on assumptions rather than documentation. By following a disciplined research chain and scoring confidence levels, it ensures that every technical decision is grounded in verifiable evidence.

Related Agents

• planner — spawns researchers during deep planning to scout technologies
• brainstormer — uses researcher findings as input for trade-off analysis
• reviewer — may invoke the researcher to verify API usage during review
• orchestrator — routes research tasks during Phase 0 orientation