zhongwei/gh-sawyer-middeleer-dot-claude-plugins-dot-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-sawyer-middeleer-dot-cla…/commands/deep-research.md
Zhongwei Li 39d22f1b82 Initial commit
2025-11-30 08:54:17 +08:00

11 KiB
Raw Permalink Blame History

Deep Research Command

Conducts comprehensive research on complex topics with technical rigor, synthesizing multiple sources including academic papers, technical documentation, industry reports, and practitioner insights.

Usage

/deep-research [topic]

Purpose

Execute a systematic research workflow that:

  • Clarifies research parameters through structured dialog
  • Creates a detailed research plan
  • Conducts parallel source investigation
  • Synthesizes findings into comprehensive documentation
  • Produces research-ready artifacts with proper citations

Prerequisites

  • Access to web search and fetch capabilities
  • Sufficient time for thorough investigation (varies by depth)

Workflow Steps

Phase 0: Topic Identification

If the user invoked the command without a topic (e.g., just /deep-research):

Ask an open-ended question: "What topic or research question would you like to investigate?"

If the user provided a topic (e.g., /deep-research distributed systems patterns):

  • Proceed directly to Phase 1 with the provided topic

Phase 1: Initial Clarification

Use the AskUserQuestion tool to gather structured feedback on research parameters.

Ask the user to clarify:

  1. Research purpose: What is the goal of this research/what angles should be explored? Suggest options contextually. (use AskUserQuestion with multiSelect: true)
  2. Scope boundaries: What should be included/excluded? Any constraints? Suggest options contextually. (use AskUserQuestion with multiSelect: true)
  3. Source preferences: Which types are most valuable? (use AskUserQuestion with multiSelect: true)
    • Academic papers and peer-reviewed research
    • Technical documentation / Industry whitepapers
    • Technical blogs from recognized experts
    • Practitioner discussions (Reddit, X, LinkedIn, HackerNews)
    • Company documentation and case studies
  4. Research depth: How many sources? (use AskUserQuestion with options for Light: 6-8, Medium: 9-14, Deep: 15+)

Phase 2: Planning & Approval

Brief preliminary investigation:

  • Search for 2-3 representative sources
  • Identify major themes, terminology, key authors/organizations
  • Note unexpected angles or adjacent topics worth exploring

Create research plan:

  1. Use template from plugins/dot-claude/commands/templates/research-plan.md
  2. Ask the user where they would like you to save your work or if you should create a new working directory
  3. Create /[RESEARCH TOPIC] inside the working directory
  4. Create and save your research plan to [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/plan.md

Plan structure:

  • Research angles: 3-5 core sub-questions or perspectives
  • Source strategy: Mix of source types with target quantities based on user preferences
  • Analysis approach: Synthesis method (thematic, comparative, chronological)
  • Expected deliverables: Final format and supporting documentation
  • Potential challenges: Known gaps, access issues, complexity factors

Phase 3: Research Execution & Synthesis

Overview

Research is conducted by spawning multiple researcher subagents simultaneously—one for each source topic. Each researcher independently fetches, analyzes, and creates a comprehensive summary of their assigned source. After all researchers complete, you synthesize their findings into a unified research document.

Research approach:

  • All sources researched simultaneously for faster execution
  • Research follows the initial research plan established in Phase 2
  • Comprehensive individual summaries from each researcher
  • Final synthesis integrates all findings after research is complete

Step 1: Setup

  1. Create synthesis file from template: plugins/dot-claude/commands/templates/research-synthesis.md
  2. Save to: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/synthesis.md
  3. Create summaries directory: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/

Step 2: Identify Research Topics

From the approved research plan, identify specific search queries to research. Aim for target source count from Phase 1 (6-8 for Light, 9-14 for Medium, 15+ for Deep).

For each research angle in the plan, identify 2-4 specific search queries to investigate:

Example:

  • Research Angle: "Performance patterns in distributed systems"
    • Query 1: "Kubernetes horizontal pod autoscaling best practices"
    • Query 2: "Netflix microservices scaling strategies"
    • Query 3: "Load balancing algorithms for distributed systems"

Create a list of N search queries to research (where N = target source count).

Step 3: Find and Validate URLs

CRITICAL: You must identify and validate specific URLs before spawning any researcher subagents.

For each search query from Step 2:

  1. Use WebSearch to find relevant sources
  2. Identify a specific URL from the search results that best addresses the query
  3. Use WebFetch with a simple prompt (e.g., "Extract the title and first paragraph") to verify each URL is accessible
  4. If a URL is not accessible, find an alternative URL for that query and validate it
  5. Compile a list of N validated URLs (one per query)

Do not proceed to Step 4 until you have N validated, accessible URLs.

Document the validated URLs clearly, noting which research angle and query each URL addresses.

Step 4: Spawn Researcher Subagents in Parallel

CRITICAL: Use a single message with multiple Task tool calls to execute all researchers in parallel.

For each validated URL from Step 3, spawn a researcher subagent using the Task tool:

Task tool parameters for each researcher:
- subagent_type: "dot-claude-agents:research-analyst"
- description: "Research [brief topic description]"
- prompt: "You are executing the researcher subagent role defined in plugins/dot-claude/agents/research-analyst.md.

Your assignment:
- Source URL: [VALIDATED_URL]
- Research focus: [specific research angle from plan]
- Research purpose: [overall research goal from Phase 1]
- Working directory: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]

Follow the instructions in plugins/dot-claude/agents/research-analyst.md to:
1. Fetch the source using WebFetch on the provided URL
2. Conduct deep analysis
3. Create comprehensive summary using plugins/dot-claude/skills/analyzing-source/templates/article-summary.md
4. Save to: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/[descriptive-filename].md

Provide a brief confirmation when complete with the key insights discovered."

Execute all N researchers in parallel by including N Task tool calls in a single message.

Step 5: Wait for Completion

All researcher subagents will execute in parallel. Wait for all to complete before proceeding.

Step 6: Review Researcher Outputs

Once all researchers have completed:

  1. List all summary files created in [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/
  2. Read each source summary file to understand what each researcher discovered
  3. Note the range of perspectives, key themes, contradictions, and gaps

Step 7: Build Comprehensive Synthesis

Now synthesize all findings into the synthesis.md file:

Synthesis approach:

  1. Identify major themes across all sources

    • Look for patterns that appear in multiple sources
    • Note areas of consensus and disagreement
    • Group related findings together

  2. Organize synthesis by themes, not by source

    • Each theme section should integrate insights from multiple sources
    • Compare and contrast different perspectives
    • Build coherent narrative for each theme

  3. For each theme, include:

    • Core insights and findings (citing source summaries using [[filename]])
    • Supporting evidence and examples from multiple sources
    • Areas of agreement across sources
    • Contradictions or debates (with citations)
    • Practical implications
    • Remaining gaps or open questions

  4. Draw evidence-based conclusions

    • Only make claims supported by multiple sources
    • Note confidence level based on source quality and consensus
    • Identify areas requiring further research

  5. Create executive summary

    • Synthesize key findings across all themes
    • Highlight most important insights
    • Note limitations of the research

Synthesis writing principles:

  • Be comprehensive yet concise—capture all important insights without redundancy
  • Cite liberally using [[source-filename]] format
  • Make connections explicit between different sources and themes
  • Distinguish between well-supported findings and tentative conclusions
  • Note source quality in your assessments (per the "Evidence Quality Assessment" sections in summaries)

Step 8: Quality Review

Verify synthesis quality:

  • All major themes from source summaries are represented
  • Synthesis is organized thematically, not source-by-source
  • Key findings are supported by citations to source summaries
  • Contradictions and debates are identified and explained
  • Conclusions are proportional to evidence strength
  • Executive summary captures essential findings
  • Writing is clear, precise, and information-dense
  • All internal links work
  • YAML frontmatter is complete

Step 9: Deliver Results

Inform user:

  • Location of synthesis and all source summaries
  • Summary of major findings and themes
  • Note any limitations (inaccessible sources, areas with thin coverage, etc.)
  • Highlight any unexpected or particularly significant discoveries

Research Approach Characteristics

Characteristics:

  • Fast execution through simultaneous source investigation
  • Efficient use of compute resources
  • Requires well-defined research questions and angles upfront

Best suited for:

  • Well-understood topics with clear structure
  • Situations where research angles can be predetermined
  • Time-sensitive research needs
  • Cases where comprehensive breadth is essential

Considerations:

  • Research plan should be thorough since pivoting mid-research isn't supported
  • Initial source topic selection is critical for comprehensive coverage

Source Quality Guidelines

Include if:

  • Provides unique insights or data
  • Represents authoritative voice
  • Offers contrarian or edge perspectives
  • Contains primary research or original analysis

Verification

Upon completion:

  1. Confirm all deliverables are created:
    • plan.md with research strategy
    • synthesis.md with thematic analysis
    • summaries/ directory with individual source analyses
  2. Verify all internal citations link correctly
  3. Check that synthesis is organized thematically, not by source
  4. Ensure conclusions are proportional to evidence

Expected Deliverables

[YOUR WORKING DIRECTORY]/
└── [RESEARCH TOPIC]/
    ├── summaries/
    │   ├── source-1-summary.md
    │   └── source-2-summary.md
    ├── plan.md
    └── synthesis.md

Notes

  • This command orchestrates multiple research-analyst subagents for parallel source investigation
  • Templates are located in plugins/dot-claude/commands/templates/
  • The analyzing-source skill provides the analysis framework used by research-analyst
  • Research quality depends on source accessibility and search result quality
Reference in New Issue View Git Blame Copy Permalink