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

code

- **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?] → Start → Poll → Report (background execution)

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

Deep Research Polling Protocol (MANDATORY)

BEFORE EVERY status check, you MUST:

•Generate user-facing text about current progress
•Do NOT call deep-research-status immediately after another MCP tool
•Track your check count (max 5)

Check #	What to Say
1	"Research underway. Currently in {phase} phase..."
2-3	"Progress: {queries_completed}/{total} queries done..."
4	"Still working ({elapsed} minutes)..."
5	Stop polling, use AskUserQuestion with options

Stall Detection: Only after elapsed_ms > 300000 AND no progress change.

NO INDEPENDENT RESEARCH: While deep research is running, do NOT use WebSearch, WebFetch, or other research tools. The deep research workflow handles all web gathering - doing your own searches is redundant and wastes resources.

MCP Tooling

Router	Actions
`research`	`chat`, `consensus`, `thinkdeep`, `ideate`, `deep-research`, `deep-research-status`, `deep-research-report`, `deep-research-list`, `deep-research-delete`, `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`, `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`
`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`

User Gates

•No args: workflow selection
•Ambiguous: clarify before auto-route
•Consensus: strategy selection
•Ideate: phase transition
•Deep: 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_id, status, report{summary, findings[], sources[]}}`