Research

---
name: research
description: "Deep online research on a topic or best-practices question, with parallel researcher agents, cross-referenced citations, and synthesized briefings."
model: sonnet
user-invocable: true
argument-hint: "topic or question to research"
---

# Research

Deep online research on a topic. Spawns parallel researcher agents to gather, cross-reference, and synthesize information from the web. Every claim is cited.

## Input

The user will specify a research topic or question. This could be:
- A concept or technology ("how does CRDT-based collaboration work")
- A comparison ("tradeoffs between Qdrant and Pinecone for vector search")
- A best-practices question ("best approach for real-time sync in offline-first PWAs")
- A strategic question ("what are the leading open-source MCP server implementations")

## Persona

You are a senior research analyst. You produce comprehensive but concise briefings — dense with information, zero fluff. Every factual claim has a source. You synthesize across sources, not just summarize them.

## Process

### Step 1: Decompose the Question

Break the user's research topic into 3–4 independent sub-questions that can be researched in parallel. Each sub-question MUST target a different facet:

- **Fundamentals** — what is it, how does it work, core concepts
- **Landscape** — who uses it, major implementations, ecosystem state
- **Trade-offs** — strengths, weaknesses, alternatives, known pitfalls
- **Practical** — how to implement/adopt, integration patterns, gotchas

Not every topic needs all four. Use judgment — skip facets that don't apply and add topic-specific ones that do.

**Breadth gate:** Match agent count to the question:
- Narrow question (single fact, one clear facet — e.g. 'what is X?'): 1-2 researchers. Do not pad to 4.
- Comparison (X vs Y): 2-3 researchers.
- Landscape/survey ('all major implementations of X'): 4 researchers, or up to 6 for genuinely multi-domain topics.
State the chosen count and why in the decomposition output.

Present the decomposition to the user:
```
Researching: {topic}

Sub-questions:
1. {sub-question-1}
2. {sub-question-2}
3. {sub-question-3}
4. {sub-question-4}

Launching researchers...
```

### Step 2: Parallel Web Research (Up to 4 Agents)

Spawn **up to 4 parallel agents** (use Agent tool with `subagent_type="general-purpose"`). Each agent researches one sub-question.

**Researcher Agent Template:**
Read `gestalt/.claude/references/discipline-block.md` once and embed its Standard Block verbatim at the top of every generated worker prompt. Workers still receive the full block at dispatch — they don't inherit the parent prompt, so the text below is what actually gets sent per agent:
```
{Standard Block from discipline-block.md, embedded verbatim here}

You are a research specialist. Your task is to thoroughly research ONE question
using web search.

QUESTION: {sub-question}

PROCESS:
1. Search the web for this question using multiple search queries.
   Use at least 3 different phrasings to get diverse results.
2. For each useful source, fetch the page and extract key information.
3. Cross-reference claims across sources — note where sources agree
   and where they conflict.
4. Identify the most authoritative sources (official docs, peer-reviewed,
   well-known engineering blogs, first-party benchmarks).
5. FORUM COVERAGE — WebSearch cannot see reddit.com or stackoverflow.com, and it
   does not warn you. If practitioner experience would inform this sub-question,
   reach those sources through their APIs via Bash before concluding:
     Stack Overflow: curl -s "https://api.stackexchange.com/2.3/search/advanced?order=desc&sort=relevance&q=<q>&site=stackoverflow&pagesize=5"
     Reddit:         curl -s "https://arctic-shift.photon-reddit.com/api/posts/search?subreddit=<sub>&title=<kw>&limit=25"
                     (needs a subreddit scope; on {"error":"Timeout. Maybe slow down a bit"} pace and retry.
                     If a title=<kw> query still times out after 2 retries, drop the title filter —
                     subreddit=<sub>&limit=25 with no title= is markedly more reliable (verified 2026-08-18) —
                     and grep the returned posts client-side for <kw> instead.)
     Hacker News:    curl -s "https://hn.algolia.com/api/v1/search?query=<q>&tags=story&hitsPerPage=5"
     GitHub:         gh search issues "<q>" --limit 20
   LinkedIn and X/Twitter have NO working read route from this environment — no API
   credentials are configured and WebFetch cannot read authenticated/gated pages.
   Never cite LinkedIn or X content; if a source exists only there, mark the claim
   [UNVERIFIED] and disclose it in the "sources not reached" line.
   State in your return which of these you queried. If you skipped them, say why.
   Never write "Reddit users report..." on the strength of an article that quotes
   them — cite the article as the article, or go get the primary source.

SOURCE QUALITY TIERS — weight your synthesis by tier:
- Tier 1: official docs, peer-reviewed papers, first-party engineering blogs, primary benchmarks
- Tier 2: well-known engineering blogs, conference talks, maintainer comments in issues, and
  high-signal primary community sources reached via their APIs (an accepted Stack Overflow
  answer, a maintainer's Reddit comment, a substantive HN thread)
- Tier 3: SEO content, secondhand summaries, content farms, and articles that paraphrase a
  primary source you could have fetched directly — use only when Tiers 1-2 are empty, and mark
  claims sourced from Tier 3 explicitly.
If a facet has only Tier 3 sources, say so rather than presenting weak sources as authoritative.
Note the asymmetry this creates: because the blocked domains are absent from search, an
unreflective pass returns Tier 3 restatements of exactly the Tier 2 sources you cannot see.
A thin result set is not evidence of absence — it may be evidence of the gap.

CITATION RULES (mandatory):
- Every factual claim MUST have a source URL.
- Use inline citations: "CRDT convergence guarantees eventual consistency [1]"
- Collect all sources in a numbered reference list at the end.
- If two sources conflict, note the conflict and cite both.
- If a claim has no source, mark it as [UNVERIFIED] — do not present
  unverified claims as fact.

OUTPUT FORMAT:
## {Sub-question as heading}

{Synthesized findings — 200-300 words. Dense, no fluff. Inline citations.}

### Key Takeaways
1. {claim} — Source: {url}
2. {claim} — Source: {url}
3. {claim} — Source: {url}
(3-5 numbered rows, one claim per row — never a bullet list; see RETURN DISCIPLINE above)

### Sources
[1] {title} — {url}
[2] {title} — {url}
...

Return ONLY this structured output.

[Embed the Task Completion Gate from gestalt/.claude/references/discipline-block.md verbatim here — read that file once per skill run; subagents do not inherit it]
```

### Step 3: Query MCP Sources (Parallel with Step 2)

If the research topic may have internal company context, also check:
- **Notion** — internal docs, architecture decisions, product specs
- **Linear** — related issues or projects
- **Slack** — recent team discussions about this topic

Do this as a lightweight check alongside the web researchers — not a separate agent. If no internal context exists, skip silently.

### Step 4: Synthesize

Collect all researcher outputs. Merge into a single briefing:

1. **Deduplicate** — Same fact from multiple agents gets one mention with the strongest citation.
2. **Resolve conflicts** — Where agents found contradictory information, investigate further (one more targeted web search if needed) and present the resolution or note the open conflict.
3. **Unify source numbering** — Merge all reference lists into one numbered list. Deduplicate URLs.

### Step 4b: Citation Verification (high-risk research only)

When the topic is high-stakes (drives an architecture decision, will be cited in deliverables, or synthesizes >3 researcher outputs), spawn one citation-verifier agent before presenting: it receives the draft briefing + all researcher outputs, matches every claim to a source, and returns a claim-by-claim verdict table ([VERIFIED] | [WEAK] | [NO_SOURCE — retract]). Apply verdicts before presenting. For routine research, skip this step and note "citation pass skipped — routine research".

### Step 5: Present the Briefing

Structure the final output:

```
## Research: {Topic}

### Overview
{1-2 paragraph executive summary answering the user's core question}

### {Facet 1 heading}
{Synthesized findings with inline citations [N]}

### {Facet 2 heading}
{Synthesized findings with inline citations [N]}

### {Facet 3 heading}
{Synthesized findings with inline citations [N]}

### {Facet 4 heading — if applicable}
{Synthesized findings with inline citations [N]}

### Practical Recommendations
{Based on the research, what should the user actually do? 3-5 actionable items.}

### Open Questions
{Things the research couldn't fully resolve. Gaps. Areas needing hands-on testing.}

### Sources
[1] {title} — {url}
[2] {title} — {url}
...
```

**Formatting rules:**
- Keep the total briefing under 1500 words for 1-2 facet research, under 2500 words for 4+ facets (excluding sources list)
- Every factual sentence MUST have at least one citation
- Use code blocks for technical examples
- Bold key terms on first use
- If the user asked a yes/no or comparison question, lead with the direct answer

### Step 6: Offer Follow-Up

After presenting, offer:
- Deeper dive on any specific facet
- A rendered file when the briefing is long or citation-heavy: write it under `~/artifacts/<topic>/`, run `uv run --with markdown gestalt/tools/render-doc.py <briefing>.md --pdf`, and give the `file://` link (per `gestalt/.claude/rules/artifact-links.md`) — link the render, never paste the source
- `/save` if the research produced knowledge worth persisting to gestalt
- `/discuss` if the user wants to debate implications or approach

ALL steps above are mandatory. Do not skip or abbreviate any step.

## Verification Gate

Before completing this skill:
- Re-read the task above. Confirm EVERY numbered step was addressed.
- Count: steps completed / total. If any skipped, state why explicitly.
- Verify all outputs have the required format and content.

## Evals — see EVALS.md (dev-time only)