zhongwei/gh-sawyer-middeleer-dot-claude-plugins-dot-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:54:17 +08:00
commit 39d22f1b82
13 changed files with 1557 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
commands/deep-research.md Normal file
View File

@@ -0,0 +1,289 @@
# 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

55
commands/templates/article-summary.md Normal file
View File

@@ -0,0 +1,55 @@
---
created: YYYY-MM-DD
source_url: [URL or citation]
source_type: [academic/industry/community/expert/case-study]
tags: [research-topic, relevant-tags]
---
# [Source Title]
**Source:** [source_url]
## Citation
[Full citation information - include authors, date, publication, DOI/URL]
## Main Points / Features / Insights
1. [Main point / feature / insight 1]
2. [Main point / feature / insight 2]
3. [Main point / feature / insight 3]
## Methodology
[Research methods used, technical approach, data sources - if applicable]
## Relevance to Research Question
[How this source addresses the research topic and which research angles it informs]
## Notable Quotes
> "[Quote 1]" (page X / timestamp)
> "[Quote 2]" (page X / timestamp)
## Critical Evaluation
**Strengths:**
- [Strength 1]
- [Strength 2]
**Limitations:**
- [Limitation 1]
- [Limitation 2]
**Potential biases:**
- [Bias 1 if any]
## Connections to Other Sources
- Supports [[other-source-1]] on [topic]
- Contradicts [[other-source-2]] regarding [point]
- Extends work by [[other-source-3]]

71
commands/templates/research-plan.md Normal file
View File

@@ -0,0 +1,71 @@
---
created: YYYY-MM-DD
research_topic: [topic]
research_purpose: [purpose from Phase 1]
target_sources: [number]
status: planning
---
# Research Plan: [Topic]
## Research Purpose
[What this research will be used for]
## Scope
**Included:**
- [Area 1]
- [Area 2]
**Excluded:**
- [Out of scope item 1]
- [Out of scope item 2]
**Constraints:**
- Temporal: [if any]
- Domain: [if any]
- Other: [if any]
## Key Questions
1. [Question 1]
2. [Question 2]
3. [Question 3]
## Research Angles
1. **[Angle 1]**: [Brief description]
2. **[Angle 2]**: [Brief description]
3. **[Angle 3]**: [Brief description]
4. **[Angle 4]**: [Brief description if applicable]
5. **[Angle 5]**: [Brief description if applicable]
## Source Strategy
**Target total:** [number] sources
**By type:**
- Academic papers: [target number or %]
- Industry reports/whitepapers: [target number or %]
- Expert blogs/technical writing: [target number or %]
- Practitioner discussions: [target number or %]
- Company docs/case studies: [target number or %]
## Analysis Approach
[How research and analysis will be conducted]
## Expected Deliverables
1. [Deliverable 1]
2. [Deliverable 2]
## Potential Challenges
- [Challenge 1 and mitigation]
- [Challenge 2 and mitigation]

122
commands/templates/research-synthesis.md Normal file
View File

@@ -0,0 +1,122 @@
---
created: YYYY-MM-DD
modified: YYYY-MM-DD
research_topic: [topic]
research_purpose: [from Phase 1]
sources_analyzed: [number]
tags: [research, synthesis, topic-tags]
type: research-synthesis
---
# [Research Topic] - Synthesis
## Executive Summary
[250 word overview of key findings, most interesting data/examples, and main conclusions]
## Research Scope & Methodology
**Purpose:** [What this research aimed to accomplish]
**Scope:** [What was and wasn't covered]
**Sources consulted:** [number] sources across [types]
**Analysis approach:** [Thematic/Comparative/Chronological]
## Key Themes & Findings
### Theme 1: [Name]
[Findings organized by theme with citations to source summaries and original files]
**Key insights:**
- [Insight 1] [[source-summary]]
- [Insight 2] [[source-summary]]
### Theme 2: [Name]
[Findings with citations]
**Key insights:**
- [Insight 1]
- [Insight 2]
### Theme 3: [Name]
[Continue for all major themes]
## Patterns & Contradictions
**Areas of consensus:**
- [What multiple sources agree on]
**Areas of debate:**
- [What sources disagree on and why]
**Surprising findings:**
- [Unexpected or counterintuitive discoveries]
## Gaps & Limitations
**Unanswered questions:**
- [Question 1]
- [Question 2]
**Research limitations:**
- [Limitation 1]
- [Limitation 2]
**Future research directions:**
- [Direction 1]
- [Direction 2]
## Conclusions & Recommendations
**Key takeaways:**
1. [Takeaway 1 with evidence]
2. [Takeaway 2 with evidence]
3. [Takeaway 3 with evidence]
**Recommendations:**
1. [Actionable recommendation 1]
2. [Actionable recommendation 2]
**Confidence levels:**
- High confidence: [Claims with strong multi-source support]
- Medium confidence: [Claims with some support or emerging evidence]
- Low confidence: [Claims requiring further validation]
## Sources Consulted
### Academic & Peer-Reviewed
- [[source-summary-1]]
- [[source-summary-2]]
### Industry Reports & Whitepapers
- [[source-summary-3]]
### Expert & Technical Blogs
- [[source-summary-4]]
### Practitioner Discussions
- [[source-summary-5]]
### Case Studies & Company Docs
- [[source-summary-6]]