| name | research-compare |
| description | Side-by-side comparison of 2-4 alternatives. Use when user says "compare", "vs", "which should I use", "X or Y", "alternatives to", or wants to choose between options. |
Research Compare
Create a structured side-by-side comparison of 2-4 alternatives to help the user make a decision.
Workflow
Phase 0: Clarify Alternatives
If the user has not specified which alternatives to compare, ask them before proceeding. For example:
- "Compare React vs Vue" — alternatives are clear, proceed.
- "Compare web frameworks" — ask: "Which frameworks would you like to compare? (e.g., Django vs FastAPI vs Flask)"
- "What database should I use?" — ask: "Which databases are you considering? (e.g., PostgreSQL vs MongoDB vs SQLite)"
Phase 1: Research
Gather information from all three sources. Research each source independently, then aggregate findings.
Note: All three subagents are used — docs_researcher gets official specs, repo_analyzer checks repositories, and web_researcher finds community opinions and benchmarks.
From Official Documentation (docs_researcher)
For EACH alternative being compared:
- Official docs URL and current version
- Primary use cases and target audience
- Key features and capabilities
- Installation and setup complexity
- Performance claims or benchmarks from official sources
- Pricing model (if applicable)
- Known limitations acknowledged by maintainers
From the Repository (repo_analyzer)
For EACH alternative being compared (if it has a public repo):
- Repository URL and metadata (stars, forks, last commit, license)
- Commit frequency and contributor count (project health)
- Issue count and response time (maintenance quality)
- Code size and dependency count
- Quality of examples and documentation in repo
- Release frequency and versioning
From Community Content (web_researcher)
- Head-to-head comparison articles
- Benchmark results from independent sources
- Migration stories (people who switched from one to another)
- Community size indicators (Stack Overflow questions, Reddit activity, Discord members)
- Common complaints and praise for each
- "I chose X because..." posts and discussions
- Industry adoption trends
Practical Articles Research (web_researcher — separate search)
Run a dedicated second search specifically targeting practitioner-oriented content for each alternative. Use queries like "practical guide to {alternative}", "{alternative} in production", "{alternative} lessons learned", "{alternative} tips", "{alternative} vs {alternative} real-world experience".
Look for:
- Production deployment guides and operational advice for each alternative
- "What I wish I knew before choosing {alternative}" posts
- Migration guides and switching cost analyses
- Common gotchas and pitfalls specific to each alternative
- Performance tuning tips and recommended configurations
- Cost breakdowns and real-world pricing experiences
- Decision flowcharts or "use X when..." rules of thumb
Phase 2: Structure
Organize content into progressive levels. references/progressive-learning.md is the source of truth.
You MUST create exactly 5 levels in this order:
- Level 1: What & Why
- Level 2: Feature Matrix
- Level 3: Tradeoff Analysis
- Level 4: Real-World Fit
- Level 5: Decision Framework
Do NOT merge, skip, or rename levels. The level names above are FINAL — use them exactly. The reference file provides depth and content guidelines only, not level names.
Phase 3: Output
Generate the comparison folder.
Output Format
Create the folder in the current working directory (./research_output/compare-{alternatives}/) containing:
research_output/compare-{alternatives}/
├── README.md # Overview and how to use this comparison
├── comparison.md # Detailed comparison with feature matrix and analysis
├── practical-takeaways.md # Decision rules and practitioner advice for each alternative
├── resources.md # All links organized by alternative and source
└── learning-path.md # Main content following the five levels
For the folder name, join alternative names with -vs- (e.g., compare-fastapi-vs-django-vs-flask).
practical-takeaways.md Guidelines
This file distills practitioner wisdom into immediately actionable decision-making content. It should be sourced primarily from the dedicated practical articles research, NOT rehashed from comparison.md or learning-path.md. Structure it with sections like:
- Decision Rules — "Use X when..., Use Y when..." concrete criteria with real scenarios
- Quick-Start Recommendation — a default pick for the most common use case, with reasoning
- Per-Alternative Tips — for each alternative, the top 3-5 things practitioners say you must know
- Migration Considerations — switching costs, common migration paths, what transfers between alternatives
- Common Mistakes — per-alternative pitfalls and anti-patterns from real-world usage
- Cost & Effort Reality Check — real-world pricing, team size, and timeline implications
Include decision flowcharts, checklists, or comparison tables where the source material supports them.
