Research Skill

Overview

Purpose: AI-powered research with multiple reasoning strategies
Scope: Five workflows, persistent thread and session management
Entry: Skill(foundry:foundry-research) or user invocation

Flow

[x?]=decision (GATE)=user approval →=sequence

- **Entry** → [route?]
  - [explicit?] → Dispatch → Execute → Persist thread → Response + thread_id
  - [thread-id?] → Resume → Dispatch → Execute → Persist thread → Response + thread_id
  - [research-id?] → SessionMgmt
  - [sessions?] → ListSessions
  - [no args?] → (GATE: choose workflow) → AutoRoute → Dispatch → Execute → Persist thread → Response + thread_id
  - [deep research?] → (GATE: confirm query + params) → Start → Poll → Report (background execution)

CRITICAL for deep research workflow: Read references/deep-research-workflow.md before execution. Contains required polling strategy and MCP parameters.

Deep Research Status Monitoring

Call deep-research-status with long-poll (wait=true). The server blocks until progress occurs or timeout elapses.

Report progress to user when each call returns.
Repeat until status is completed or failed.
If 2 consecutive responses return "changed": false, offer user options via AskUserQuestion (keep waiting, cancel, narrow query).

CRITICAL — Do NOT supplement deep research with your own searches. While deep research is running, do NOT call WebSearch, WebFetch, tavily_search, tavily_extract, or any other web/research tools. The deep research workflow handles all source gathering internally. Only use external search tools if the user explicitly asks you to search independently. When deep research is in the SUPERVISION phase and progress seems slow, this is normal — report status and keep polling. Do not interpret normal processing time as a failure that needs workaround.

MCP Tooling

Router	Actions
`research`	`chat`, `consensus`, `thinkdeep`, `ideate`, `deep-research`, `deep-research-status`, `deep-research-report`, `deep-research-list`, `deep-research-delete`, `deep-research-evaluate`, `thread-list`, `thread-get`, `thread-delete`, `node-execute`, `node-record`, `node-status`, `node-findings`

MCP Contract

Action	Required	Optional	Errors
`chat`	`prompt`	`thread_id`, `provider_id`	`THREAD_NOT_FOUND`
`consensus`	`prompt`	`providers`, `strategy`	`NO_MODELS_AVAILABLE`
`thinkdeep`	`prompt`	`thread_id`, `depth`	`MAX_DEPTH_EXCEEDED`
`ideate`	`prompt`	`thread_id`, `phase`	`INVALID_PHASE`
`deep-research`	`query`	`max_iterations`, `max_sub_queries`, `max_sources_per_query`, `follow_links`	`RESEARCH_TIMEOUT`
`deep-research-status`	`research_id`	-	`RESEARCH_NOT_FOUND`
`deep-research-report`	`research_id`	-	`RESEARCH_NOT_FOUND`
`deep-research-list`	-	`limit`, `completed_only`	-
`deep-research-delete`	`research_id`	-	`RESEARCH_NOT_FOUND`
`deep-research-evaluate`	`research_id`	-	`RESEARCH_NOT_FOUND`
`thread-*`	`thread_id`	`limit`	`THREAD_NOT_FOUND`
`node-status`	`spec_id`, `research_node_id`	-	`NODE_NOT_FOUND`
`node-execute`	`spec_id`, `research_node_id`	`prompt`	`NODE_NOT_FOUND`, `INVALID_TYPE`
`node-record`	`spec_id`, `research_node_id`, `result`	`summary`, `key_insights`, `recommendations`, `confidence`	`NODE_NOT_FOUND`
`node-findings`	`spec_id`, `research_node_id`	-	`NODE_NOT_FOUND`, `NO_FINDINGS`

Workflow Selection

Signal	Workflow
Follow-up, iteration	`chat`
Multiple perspectives	`consensus`
Complex problem	`thinkdeep`
Brainstorming	`ideate`
Comprehensive research, multiple sources	`deep research`

User Gates

No args: workflow selection
Ambiguous: clarify before auto-route
Consensus: strategy selection
Ideate: phase transition
Deep: pre-launch query confirmation, then progress updates during background execution

Output Formats

Workflow	Response
`chat`	`{response, thread_id, model}`
`consensus`	`{responses[], synthesis, strategy}`
`thinkdeep`	`{findings[], confidence, thread_id}`
`ideate`	`{ideas[], phase, selected[]}`
`deep research`	`{research_id, status, report{summary, findings[], sources[], topic_research_results[], contradictions[], content_fidelity, evaluation}}`

foundry-research