deep-researchDeep, iterative, multi-source research that explores a topic from multiple perspectives, detects contradictions, and produces a comprehensive vault note with fact-level citations and a confidence map. Use this skill whenever the user says /deep-research, "deep research X", "research X thoroughly", "investigate X deeply", "I need to really understand X", or …
Independent GitHub snapshot · Automated classification · Original documentation governs
The architecture is inspired by Stanford's STORM (perspective discovery + outline-first), Anthropic's multi-agent research system (parallel exploration + intelligent critique), and pi-autoresearch (living state files that survive context resets).
<Use_When>
<Do_Not_Use_When>
Parse $ARGUMENTS for the topic and optional depth flag:
--quick: faster, fewer rounds, sonnet everywhere, no perspective discovery--deep: more rounds, opus for critic and synthesis, outline reviewed by userCreate the workspace:
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-30)
WORK_DIR="temp/research-${TOPIC_SLUG}"
mkdir -p "$WORK_DIR"/{findings,gaps}
Resume check: Before creating, check if the workspace already exists:
ls "$WORK_DIR/state.md" 2>/dev/null
If state.md exists, read it and ask the user: "Found incomplete research on
[topic] (round N). Resume or start fresh?" If resuming, read state.md to
determine which stage to skip to.
Tell the user what's happening:
Deep researching "{topic}" ({depth mode}).
Setting up workspace at {WORK_DIR}...
Read the agent definition:
Read(".claude/skills/deep-research/agents/research-planner.md")
Launch the planner agent:
Agent(
model="sonnet",
prompt="You are Research Planner. Follow these instructions exactly:
[INSERT FULL CONTENT OF agents/research-planner.md HERE]
TOPIC: {topic}
DEPTH_MODE: {quick|standard|deep}
WORK_DIR: {WORK_DIR}
Write state.md and ideas.md to the WORK_DIR."
)
After the planner completes, read state.md briefly and tell the user:
Perspectives identified: {list}
Sub-questions: {count}
Exploration ideas: {count}
Starting exploration...
Read the agent definition and source tiers reference:
Read(".claude/skills/deep-research/agents/research-explorer.md")
Read(".claude/skills/deep-research/references/source-tiers.md")
Read ideas.md and pick the 3-5 highest-priority unexplored ideas.
For EACH selected idea, launch an explorer agent in the background:
Agent(
model="sonnet",
run_in_background=true,
prompt="You are Research Explorer. Follow these instructions exactly:
[INSERT FULL CONTENT OF agents/research-explorer.md HERE]
SOURCE TIERS REFERENCE:
[INSERT FULL CONTENT OF references/source-tiers.md HERE]
ANGLE: {the idea to explore}
PERSPECTIVE: {which perspective this serves}
QUERIES: {the search queries from ideas.md}
STATE_CONTEXT: {summary from state.md — what's already known}
OUTPUT_FILE: {WORK_DIR}/findings/angle-{NN}-{slug}.md
Write your findings to OUTPUT_FILE using the Write tool."
)
Wait for all explorer agents to complete. Verify each output file exists:
ls {WORK_DIR}/findings/
Update ideas.md — mark explored ideas as [x]. If explorers discovered new
threads, append them to ideas.md under "## Discovered During Research".
Tell the user:
Round {N} complete: explored {count} angles, found {count} sources.
Running critique...
For --quick mode: skip the critic agent entirely. Instead, briefly review the
findings yourself — check if any sub-questions are obviously thin. If so, do ONE
more targeted search round. Then proceed to Stage 5.
For standard and --deep mode: Launch the critic agent.
Read the agent definition:
Read(".claude/skills/deep-research/agents/research-critic.md")
Agent(
model="opus",
prompt="You are Research Critic. Follow these instructions exactly:
[INSERT FULL CONTENT OF agents/research-critic.md HERE]
WORK_DIR: {WORK_DIR}
ROUND: {current round number}
Read all files in the workspace, then write your critique to
{WORK_DIR}/gaps/critique-round-{N}.md.
Also update {WORK_DIR}/state.md with the coverage map.
If you have new research ideas, append them to {WORK_DIR}/ideas.md."
)
Read the critic's output: {WORK_DIR}/gaps/critique-round-{N}.md
Check the recommendation: CONTINUE or SUFFICIENT.
If CONTINUE AND within guardrails:
ideas.md for new anglesIf SUFFICIENT OR guardrails hit:
Guardrails (override critic recommendation if needed):
critique-round-*.md files existTell the user:
Critic says: {CONTINUE/SUFFICIENT}. {brief reason}
{If continuing: "Exploring {N} more angles..."}
{If done: "Evidence base ready. Building outline..."}
Build an outline that maps each section to its supporting evidence. This is the STORM discipline — commit to structure before writing to prevent hallucination.
Read the final critique, all findings files, and state.md. Then write
{WORK_DIR}/outline.md with this structure:
# Outline: {Topic}
## TL;DR
- {Key finding 1} ← supported by: angle-{NN}, angle-{NN}
- {Key finding 2} ← supported by: angle-{NN}
- {Key finding 3} ← supported by: angle-{NN}, angle-{NN}
## Section: {Theme 1 — insight as heading}
- Key point: {insight}
- Sources: angle-{NN} (claims X,Y), angle-{NN} (claim Z)
- Vault links: [[(Type) Note]] if relevant
## Section: {Theme 2 — insight heading}
- Key point: {insight}
- Sources: ...
## Section: Where Experts Disagree
- Contradiction 1: angle-{NN} vs angle-{NN} on {topic}
- Contradiction 2: ...
## Section: What's Still Uncertain
- {Gap from critic}
- {Single-source claim}
## Confidence Map Notes
- {Finding}: {confidence level} — {evidence basis}
For --deep mode: Show the outline to the user and wait for approval:
"Here's the outline. Want me to adjust anything before I write the full note?"
For standard and --quick: Proceed automatically.
Read the agent definition:
Read(".claude/skills/deep-research/agents/research-synthesizer.md")
Launch the synthesizer:
Agent(
model="opus", # sonnet for --quick
prompt="You are Research Synthesizer. Follow these instructions exactly:
[INSERT FULL CONTENT OF agents/research-synthesizer.md HERE]
WORK_DIR: {WORK_DIR}
OUTPUT_FILE: {WORK_DIR}/synthesis.md
Read outline.md, all findings files, all gap files, and state.md.
Write the complete vault note body to OUTPUT_FILE.
Do NOT include frontmatter — just the note content starting with # title."
)
Read {WORK_DIR}/synthesis.md
Generate timestamp:
date +%Y%m%d%H%M%S
Determine subfolder — match the topic to existing vault folders:
notes/ml/notes/startup/notes/psychology/notes/finance/notes/research/Create the vault note using mcp__obsidian-vault__write_note or Write:
---
id: {YYYYMMDDHHMMSS}
type: note
processing_status: processed
created_date: {YYYY-MM-DD}
updated_date: {YYYY-MM-DD}
---
{synthesis.md content}
Report to user:
Research complete! Created: {note path}
- Sources: {N} web, {N} academic, {N} community, {N} vault
- Exploration rounds: {N}
- Contradictions found: {N}
- Key uncertainty: {biggest gap}
Suggested next steps:
- Extract terms: {list of concepts for extraction}
- Related research: {follow-up topics}
- Vault connections: {notes that should link to this}
Workspace at {WORK_DIR}/ — delete when done.
<Tool_Usage>
<Escalation_And_Stop_Conditions>
$ARGUMENTS