Deep Research

Deep Research

Purpose

Execute a multi-stage research pipeline that decomposes a vague topic into structured subtopics, gathers usage-focused information from authoritative sources via parallel agents, validates claims for consistency, produces a synthesis-grade report, and converts raw findings into a reusable industry-grade skill. This is invoked internally by the deep-research skill — never call the pipeline stages directly.

When to Use

• A comprehensive, multi-faceted report is needed covering 3+ subtopics
• The topic requires crawling multiple authoritative sources (docs, API refs, guides)
• The output must be structured, validated, and free of hallucination
• The question cannot be answered by a single source or quick lookup

When Not to Use

• A quick factual answer is needed — use websearch instead
• Only one source needs to be checked — use the MCP data plane tools directly
• The topic is a simple how-to question — answer directly
• Real-time data is needed (stock prices, live scores) — use web-research

Inputs

| Input | Type | Required | Description | |---|---|---|---| | topic | string | Yes | The research topic or question | | depth | enum | No (default: standard) | quick, standard, deep | | focus | enum | No (default: usage) | usage, architecture, comparison, general | | constraints | string | No | Additional rules from AGENTS.md or user | | output_mode | enum | No (default: formatted) | formatted, unformatted | | skill_mode | enum | No (default: skill) | skill, no-skill |

Expected Outputs

| Output | Condition | Description | |---|---|---| | research/-plan.md | Always | Structured plan with subtopics, questions, seed URLs | | research/-raw/ | Always | One file per subtopic from parallel research agents | | research/-validated.md | Always | Cross-checked, deduplicated, hallucination-filtered | | research/-report.md | formatted mode | Final synthesis with all findings, code examples, sources | | .opencode/skills//SKILL.md | skill mode | Reusable skill generated from findings |

Internal Workflow

Stage 1: Plan

Internal planner agent decomposes topic into 3-7 subtopics with questions and seed URLs from authoritative sources only. For JS-rendered content, Playwright MCP tools (browser_navigate, browser_snapshot) are available for interactive browsing during URL discovery.

Stage 2: Research (Parallel)

Internal research agents run concurrently — one per subtopic. Each crawls seed URLs, extracts code examples, API signatures, and edge cases. For JS-rendered pages, agents use Playwright MCP tools (browser_navigate, browser_snapshot).

Stage 3: Validate

Internal validator cross-checks all subtopic outputs: removes unsupported claims, flags contradictions, deduplicates findings.

Stage 4: Synthesize

Internal synthesizer merges validated research into a final report with sections: Overview, Getting Started, Core Content, Advanced Patterns, Migration Guide, Best Practices, Edge Cases, Sources.

Stage 5: Output

Internal output writer saves research results based on output mode:

• formatted (default): Produces a structured report at research/-report.md with sections: Overview, Getting Started, Core Content, Advanced Patterns, Migration Guide, Best Practices, Edge Cases, Sources
• unformatted: Saves raw scraped data as individual markdown files in research/-raw/ with minimal processing

Raw data is always saved to research/-raw/ regardless of mode.

Stage 6: Skill Conversion (conditional)

AI uses the skill-builder skill to convert the raw findings into a reusable SKILL.md file — only when skill mode is selected:

• Reads all research/-raw/*.md files
• Identifies reusable patterns, APIs, and best practices
• Writes a structured SKILL.md with frontmatter, workflow steps, gotchas, and references
• Places the skill in .opencode/skills// for future coding use
• Reports the skill path to the user

Required Checks

• [ ] Planner ran first (never skip)
• [ ] Research agents ran in parallel
• [ ] Validator ran after all research completed
• [ ] Every claim has a source URL
• [ ] No blog posts or changelogs used as sources

Failure Modes

| Failure Condition | Response | |---|---| | Planner produces 50% claims as unsupported | Re-run research with better URLs | | Pipeline exceeds max iterations | Stop and return partial results |

Examples

Example 1: Full research with skill (default)

Trigger: /forge-research Next.js 16 caching --depth=deep Result: research/nextjs16-report.md + .opencode/skills/nextjs16/SKILL.md

Example 2: Raw output only, no skill

Trigger: /forge-research Next.js 16 caching unformatted no-skill Result: research/nextjs16-raw/*.md (raw files only)

Example 3: Formatted report, no skill

Trigger: /forge-research Python 3.14 pattern matching formed no-skill Result: research/python314-report.md (structured report only)

References

| Reference | Path | |---|---| | RESEARCH_INSTRUCTIONS.md | ./RESEARCH_INSTRUCTIONS.md |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Razaib-khan
• Source: Razaib-khan/ForgeWeave
• License: MIT

Install and usage instructions live in the source repository linked above.