Research Orchestrator Skill

Overview

Research Orchestrator enables comprehensive research projects using an orchestrator-workers pattern. The main orchestrator coordinates without reading content directly, while specialized researchers write sections to files independently. This architecture supports:

• Large-scale research exceeding context window limits
• Parallel execution of independent research sections
• Strict validation with count and schema enforcement
• Interactive dashboards via pre-built HTMX/Alpine.js components
• Extensible researchers for domain-specific needs

When to Use

• Multi-section research reports requiring comprehensive analysis
• Competitive analysis with specific count requirements ("10 competitors")
• Market research spanning multiple segments and trends
• Technical deep-dives with benchmarks and comparisons
• Any research where you need to ensure specific items are covered

Quick Start

1. Invoke: Use /research <topic> or ask for deep research naturally
2. Clarify: Answer the orchestrator's questions about scope and requirements
3. Wait: Parallel researchers gather data while you track progress
4. Validate: Validation ensures all requirements are met
5. Receive: Get an interactive dashboard or JSON report

Key Concepts

Orchestrator-Workers Pattern

The orchestrator coordinates but never reads section content directly:

• Delegates to schema-builder for research structure
• Spawns {type}-researcher agents for each section
• Uses reviewer agent when content review is needed
• Runs validator agent to check completeness
• Assembles final output via scripts

Count Validation

Specify counts in research requests to enforce completeness:

• "Analyze 10 competitors" → Validates exactly 10 profiles
• "Identify 5 market segments" → Validates exactly 5 segments
• "Compare 3 technologies" → Validates exactly 3 comparisons

File-Based Architecture

All section data is written to files:

output/
├── schemas/          # JSON schemas per section
├── sections/         # Research content (JSON)
├── validation/       # Validation results
└── final/            # Assembled reports and dashboards

Available Agents

Agent	Role	When Used
research-orchestrator	Coordinates entire workflow	Main entry point
schema-builder	Creates outline + schemas	Phase 2: Structure
default-researcher	General web research	Overview sections
competitor-researcher	Company profiling	Competitive analysis
market-researcher	Market sizing and trends	Market research
technical-researcher	Technical deep-dives	Technology analysis
reviewer	Reviews content for orchestrator	Quality checks
validator	Runs validation scripts	Completeness verification
generalist	Ad-hoc tasks	Gap filling, verification

Workflow Phases

Phase 1: Clarification

Orchestrator asks 2-4 questions:

• What is the scope and depth needed?
• Are there specific entities to include?
• What are the count requirements?
• Preferred output format?

Phase 2: Schema Creation

Schema-builder creates:

• output/schemas/outline.json with section definitions
• output/schemas/{section}.schema.json with validation rules
• Embedded count requirements (minItems constraints)

Phase 3: Research Execution

Researchers are spawned in parallel for independent sections:

• Each reads its schema
• Conducts web research
• Writes JSON to output/sections/{section}.json

Phase 4: Validation

Validator runs:

python scripts/validate-research.py --schemas output/schemas/ --sections output/sections/

Returns specific failures:

• Count shortfalls: "Expected 10, found 7"
• Empty fields: "content[2].body is empty"
• Schema violations: "Required field 'sources' missing"

Phase 5: Assembly

Once validation passes:

• assemble-report.py combines section JSONs
• render-dashboard.py generates interactive HTML

Output Options

Interactive Dashboard

HTMX/Alpine.js powered with:

• Collapsible sections
• Sortable/filterable tables
• Charts and visualizations
• Search functionality

JSON Report

Structured data for programmatic use:

{
  "title": "Research Topic",
  "sections": [...],
  "metadata": {...}
}

Print-Friendly Report

Optimized for PDF export and printing.

Customization

Themes

Located in assets/themes/:

• default/ - Clean, modern design
• corporate/ - Professional, conservative
• minimal/ - Reduced visual elements

Adding Researchers

See researchers/README.md for creating domain-specific researchers.

Logo and Branding

Replace assets/templates/logo-placeholder.svg with your logo.

Additional Resources

Reference Files

• references/schema-patterns.md - JSON schema patterns for research
• references/validation-rules.md - Validation rule documentation
• references/output-formats.md - Output format specifications

Scripts

• scripts/validate-research.py - Main validation script
• scripts/assemble-report.py - JSON assembly
• scripts/render-dashboard.py - HTML rendering

Components

Pre-built HTMX/Alpine.js components in assets/components/:

• section-card.html - Collapsible sections
• data-table.html - Sortable tables
• competitor-grid.html - Comparison grids
• chart-container.html - Chart.js integration
• See full list in components directory

Example Usage

Competitive Analysis

/research AI code assistant market competitive analysis with 10 competitors

Market Research

/research sustainable packaging industry market research with 5 segments

Technical Comparison

/research WebAssembly vs JavaScript performance technical deep-dive

Troubleshooting

Validation Keeps Failing

• Check specific failure messages
• Ensure count requirements are exact
• Look for placeholder text
• Verify all required fields populated

Research Taking Too Long

• Reduce scope with clarifying questions
• Focus on fewer sections initially
• Use parallel execution for independent sections

Missing Data in Output

• Review section schemas for requirements
• Check researcher has correct sources configured
• Verify web search is returning results