research

Research & Synthesize Documentation

You are helping the user research an external product, topic, or set of sources and produce structured documentation artifacts from public information.

Invocation

This skill is invoked as /greenfield-start:research <argument>.

The argument is free-form. Your first job is to determine the research mode.

Phase 1: Parse Input & Detect Mode

Examine the argument provided after /greenfield-start:research.

No Argument

If no argument was provided, ask:

What product, topic, or URL would you like me to research?

Wait for the user's response, then proceed with mode detection on their answer.

Mode Detection

Constrained mode — the input contains one or more URLs or GitHub repo references (patterns like https://, http://, github.com/, gitlab.com/):

Examples:

• https://bear.app/features/
• github.com/org/repo
• https://docs.example.com/api https://blog.example.com/architecture

In constrained mode, the provided URLs are the confirmed source list. Derive a subject name from the URLs (e.g., domain name, repo name, or page title) to use in the dispatch prompt and output directory slug. Skip to Phase 3.

Open mode — the input is a product name, topic, or description without URLs:

Examples:

• Bear note-taking app
• event-driven architecture for IoT pipelines

In open mode, proceed to Phase 2 (Source Discovery).

Ambiguous input — if the input is a single word or short phrase that could be either a specific product or a general topic, ask one clarifying question:

Are you looking to research a specific product called "", or the general topic of ""?

Then proceed based on the answer.

Phase 2: Source Discovery (Open Mode Only)

Use WebSearch to find relevant public sources for the subject. Target:

• Official product/project websites and documentation
• API documentation
• Public GitHub repositories
• Technical blog posts and articles
• Comparison/review articles that detail features

Present Sources for Confirmation

Present a numbered list of discovered sources with a one-line description of each:

I found these sources for "<subject>":

1. <url> — <one-line description>
2. <url> — <one-line description>
...

Which of these should I analyze? (all / comma-separated numbers / "also add <url>" / "drop <number>")

User Confirmation Gate

The user may:

• Approve all sources
• Select a subset by number (e.g., "1, 3, 5")
• Drop specific sources (e.g., "drop 4")
• Add additional URLs (e.g., "also add https://example.com/docs")

This is a single confirmation round. Do not search again unless the user explicitly asks (e.g., "can you also search for X").

After confirmation, proceed to Phase 3 with the confirmed source list.

Phase 3: Dispatch Research Analyzer

Determine Output Directory

Generate the output directory path:

1. Get today's date in YYYY-MM-DD format
2. Generate a slug from the subject: lowercase, replace spaces and non-alphanumeric characters with hyphens, collapse consecutive hyphens, trim leading/trailing hyphens
3. Combine: docs/research/<date>-<slug>/
4. If that directory already exists, append -2 (then -3, etc.) until unique

Dispatch the Subagent

Dispatch the research-analyzer agent with the following prompt:

Research subject: <subject name/description>
Output directory: <output_dir>
Research date: <YYYY-MM-DD>

Sources to analyze:
1. <url> — <description>
2. <url> — <description>
...

Analyze all sources and synthesize documentation artifacts into the output directory.
Follow your artifact format specifications exactly.

The subagent will work autonomously and produce files in the output directory.

Phase 4: Present Summary

After the subagent completes, read the generated README.md from the output directory and present a summary to the user:

Research complete. Artifacts written to `<output_dir>/`:

**Artifacts produced:**
- <artifact> (confidence: <level>)
- ...

**Skipped:**
- <artifact> — <reason>

**Notable gaps or conflicts:**
- <summary>

You can review the full research index at `<output_dir>/README.md`.
To integrate these into your project documentation later, a `/greenfield-start:integrate` skill is planned (not yet built).

If the subagent reported any unreachable sources, mention those in the summary.