research

User Input

$ARGUMENTS

You MUST consider the user input before proceeding.

Outline

Phase 0: Setup

1. Parse topic from $ARGUMENTS
2. If empty, ask user what to research

1. Auto-detect research mode based on topic keywords:
2. Competitor Analysis: "alternatives", "vs", "competitors", "pricing", "compare", product/company names
3. Technical Research: "API", "how to", "best practices", "parsing", "library", "framework", "implementation", "github"
4. If unclear, proceed with general research approach

1. Generate output path:
2. Slugify topic: lowercase, replace spaces with -, remove special chars
3. Path: {REPO_ROOT}/research/{topic-slug}.md
4. Create directory if not exists: mkdir -p research

1. Initialize research document with metadata (atomic write):

```markdown # Research: {Topic}

Date: {YYYY-MM-DD} Mode: {Detected Mode} Status: In Progress ```

1. Generate subtopics (query decomposition):
2. Decompose main topic into 3-5 focused subtopics
3. Adapt subtopics based on detected mode:

For Competitor Analysis:

• What is {topic}? (market category, core value prop)
• Who are the main players? (direct competitors)
• How do they compare? (features, pricing, positioning)
• What are the problems? (complaints, limitations)
• What do users recommend? (community preferences)

For Technical Research:

• What is {topic}? (definition, core concepts)
• How does it work? (mechanics, implementation)
• What are the alternatives? (other approaches)
• What are the problems? (limitations, gotchas)
• What are best practices? (recommendations, patterns)

Show the research plan to user before starting deep research.

Phase 1: Scope Clarification (if needed)

Only ask clarifying questions if topic is genuinely ambiguous. Max 3 questions.

Present questions one at a time with recommendation:

Recommended: Option X - {reasoning}

| Option | Description | |--------|-------------| | A | ... | | B | ... |

Possible questions (only if truly unclear):

1. Scope: Which aspects are most important? (features, pricing, implementation, all)
2. Depth: Quick overview or deep dive?
3. Targets: Any specific products/libraries to include or exclude?

Skip clarification if topic is clear enough to proceed.

Phase 2: Deep Research Execution

Core principle: Multi-pass search with parallel exploration and source triangulation.

Step 1: Parallel Research (MANDATORY for complex topics)

Launch 2-3 parallel agents, each handling one focused subtopic. Use whatever multi-agent mechanism is available (Agent tool, spawn_agent, etc.).

Rules for parallel research:

• Each agent gets ONE focused subtopic
• Agents should use web search and web fetch tools
• Wait for all agents to complete before moving to Step 2
• For simple topics: skip parallel agents, do sequential search

Step 2: Multi-Pass Search Strategy

After parallel research, fill gaps with targeted passes:

Pass 1 — Broad Discovery (if not done by agents):

• General queries about the topic
• Overview articles, official docs

Pass 2 — Expert Sources:

• site:news.ycombinator.com {topic} — developer opinions, real experiences
• site:reddit.com {topic} — community insights, discussions
• site:github.com {topic} stars:>100 — proven solutions, popular repos

Pass 3 — Gap Analysis & Targeted Search: After each pass, evaluate internally:

• What's confirmed? What's still missing?
• What claims need verification from another source?

Pass 4 — Counter-Arguments (ALWAYS do this):

• {topic} problems, {topic} criticism, why not use {topic}

Pass 5 — Source Triangulation: For key facts: verify from 2-3 independent sources.

Atomic Writes

After each significant block of findings, write to the research document.

Stopping Criteria

• All subtopics from Phase 0 covered
• Key claims verified from multiple sources
• Counter-arguments documented
• New searches don't yield new information
• User says "enough"

Phase 3: Synthesis & Documentation

Confidence Ratings

• 🟢 High: 3+ sources, official docs, recent data
• 🟡 Medium: 1-2 sources, reasonably recent
• 🔴 Low/Unverified: Single source, outdated, or conflicting info

Structure findings based on detected mode:

For Competitor Analysis

## Executive Summary
{2-3 paragraphs: key findings, market landscape, recommendation}

## Market Overview
{Brief description of the market/category}

## Competitors

### {Competitor 1}
- **Overview**: {what it is, who it's for}
- **Key Features**: {bullet list}
- **Pricing**: {tiers, free tier, enterprise options}
- **Strengths**: {what they do well}
- **Weaknesses**: {gaps, issues, limitations}
- **User Sentiment**: {reviews summary if found}

### {Competitor 2}
...

## Feature Comparison

| Feature | {Comp 1} | {Comp 2} | {Comp 3} |
|---------|----------|----------|----------|
| ... | ... | ... | ... |

## Pricing Comparison

| Tier | {Comp 1} | {Comp 2} | {Comp 3} |
|------|----------|----------|----------|
| Free | ... | ... | ... |
| Pro | ... | ... | ... |

## Recommendations
- **Primary**: {what to choose and why}
- **Alternatives**: {when to consider others}
- **Open Questions**: {what needs further investigation}

For Technical Research

## Executive Summary
{2-3 paragraphs: problem, solution approach, recommendation}

## Technology Overview
{What the technology/approach is about}

## Best Practices
- **{Practice 1}**: {description + rationale}
- **{Practice 2}**: {description + rationale}

## Implementation Patterns

### Pattern: {Name}
{code example if applicable}
**When to use**: {context}
**Trade-offs**: {pros/cons}

## Alternatives Comparison

| Criterion | {Option 1} | {Option 2} | {Option 3} |
|-----------|------------|------------|------------|
| Performance | ... | ... | ... |
| Complexity | ... | ... | ... |
| Community | ... | ... | ... |

## Security Considerations
- {Security concern 1}
- {Security concern 2}

## Recommendations
- **Primary**: {recommended approach}
- **Alternatives**: {when to consider others}
- **Open Questions**: {what needs team decision}

Phase 4: Finalize & Report

1. Update document status to "Final"

1. Add Disputed/Unverified Claims section (if any):

```markdown ## Disputed/Unverified Claims

• {Claim 1}: {why uncertain — conflicting sources, single mention, etc.}
• {Claim 2}: {needs verification — only found in one place}

```

1. Add Research Metadata:

```markdown ## Research Metadata

• Sources consulted: {N}
• Search passes: {N}
• Subtopics covered: {list}
• Parallel agents used: Yes/No
• Research depth: Deep / Standard

```

1. Compile Sources section with annotations:

```markdown ## Sources

1. [{Title}]({URL}) - {brief annotation: why valuable}
2. ...

```

1. Report to user:
2. Path to research document
3. Brief summary of key findings (3-5 bullet points)
4. Highlight any disputed/unverified claims
5. Suggested next steps if applicable

Rules

• Absolute paths only
• Atomic writes after each significant finding block
• No artificial search limits — research until topic is covered
• Sources at end, not inline
• Match user's language in output

Error Handling

• If no relevant results: note the gap, suggest query refinement
• If conflicting information: document both perspectives, recommend verification approach
• If search fails: retry once, then document limitation

Examples

/research telegram aggregator alternatives
/research CoinGecko API alternatives
/research NATS vs Kafka for real-time events
/research telegram message parsing best practices
/research python async web scraping
/research github telegram bot python