Synthesis

Synthesis

You are performing multi-source research synthesis — aggregating, comparing, and composing insights from multiple sources (papers, blog posts, docs, discussions, code) into a coherent answer. The goal is a single composed response that draws on all sources, not a list of summaries.

This skill exists because loading 3+ full web pages or documents into your main context window is wasteful and noisy. The pattern (Recursive Language Model — see the RLM substrate section in CLAUDE.md) is: fetch each source, store it in shared state, dispatch a sub-agent per source to extract key claims, then dispatch a final synthesis sub-agent to compose the answer.

This skill complements the existing research skill. Research handles single small sources (fetch → read → answer). Synthesis handles the cases where multiple sources or large sources make direct reading impractical.

When to use

Trigger this skill when ANY of these hold:

• 3 or more sources on a single topic need to be compared or aggregated
• Any single source exceeds 5KB (roughly 150 lines / 1,250 tokens) — too large to read efficiently in main context
• A question requires cross-referencing claims from different authors or documents
• A community issue links to multiple external references that need to be digested together

When NOT to use

• 1-2 sources, all under 5KB. Use the research skill's single-source procedure — direct curl and read. Sub-agent overhead exceeds the savings.
• The sources are code files, not prose. Use explore-codebase instead — it's optimized for structural code comprehension, not prose synthesis.
• You already know the answer. Don't synthesize to confirm what you already understand. That's burning sub-agent budget for validation theater.
• You're inside a sub-agent at depth 3. Stop. Return what you have. Do not dispatch further.

Procedure

1. Frame the research question (single sentence)

Examples of well-framed questions:

• "What are the tradeoffs between streaming JSON parsing libraries in Rust (serde_json, simd-json, sonic-rs)?"
• "How do different coding agents (Aider, Continue, Cursor) handle context window management?"
• "What does the academic literature say about recursive LLM agent architectures?"

A good question names a specific topic and what you want to learn. Don't ask vague questions like "tell me about Rust".

2. Gather sources

Fetch each source via bash. Typical patterns:

# Web page
curl -sL "https://example.com/article" | sed 's/<[^>]*>//g' | head -500

# GitHub README
curl -sL "https://raw.githubusercontent.com/org/repo/main/README.md"

# Documentation page
curl -sL "https://docs.rs/crate/latest/crate/" | sed 's/<[^>]*>//g' | head -500

# Search results (to find sources)
curl -s "https://lite.duckduckgo.com/lite?q=your+query" | sed 's/<[^>]*>//g' | head -60

Aim for 3-7 sources. More than 7 rarely adds insight — diminishing returns set in fast.

3. Decide: direct synthesis or sub-agent dispatch?

Estimate total content size:

echo "$SOURCE_1" | wc -c
# repeat for each source

• Total < 5KB across all sources: Synthesize directly in your main context. Skip sub-agents — the overhead isn't worth it.
• Total ≥ 5KB: Proceed with sub-agent dispatch (Step 4).

4. Store sources in shared state

Store each source under a namespaced key:

shared_state set key="synthesis.<topic>.source-1" value="<source 1 content>"
shared_state set key="synthesis.<topic>.source-2" value="<source 2 content>"
shared_state set key="synthesis.<topic>.source-3" value="<source 3 content>"

Namespace convention: synthesis.<topic>.source-<N> where <topic> is a short kebab-case slug (e.g., synthesis.rust-json-parsers.source-1).

4a. Chunking for large sources (>30KB)

If any single source exceeds 30KB (~120,000 bytes):

1. Split into chunks of ~25KB at paragraph boundaries (double newline \n\n). Don't split mid-sentence.
2. Store each chunk separately:

   shared_state set key="synthesis.<topic>.source-<N>.chunk-1" value="<first ~25KB>"
   shared_state set key="synthesis.<topic>.source-<N>.chunk-2" value="<next ~25KB>"

3. Dispatch one sub-agent per chunk (same prompt as Step 5, but referencing the chunk key instead of the source key).
4. Merge chunk summaries before the final synthesis: combine key_claims and key_quotes from all chunks of the same source, deduplicate, and store the merged result as the source's summary.

5. Dispatch per-source sub-agents

For each source, dispatch a sub-agent with a focused extraction question. One source per sub-agent — sources are the natural unit of synthesis.

sub_agent: You are extracting key claims from a research source.

The source is stored in shared state under key "synthesis.<topic>.source-<N>".
Read it with: shared_state get key="synthesis.<topic>.source-<N>"

Research question: <your single-sentence question from step 1>

Extract the source's relevant claims and evidence. Reply with ONLY a JSON object (no markdown fences, no prose):
{
  "key_claims": ["claim 1", "claim 2", ...],
  "key_quotes": ["exact quote or close paraphrase with attribution", ...],
  "relevance": "high|medium|low",
  "confidence": 0.0-1.0,
  "source_type": "paper|blog|docs|discussion|code|other",
  "deeper_question": "a follow-up question if something is unclear, or null"
}

Skills do not chain. Sub-agents don't load this skill or any other; include the full question and shared-state key reference directly in the sub-agent's prompt.

5a. Handle sub-agent responses

Parse each sub-agent's response as JSON:

1. Valid JSON with all fields: Store the summary in shared state under synthesis.<topic>.summary-<N>.
2. Malformed JSON but readable text: Extract what you can. Construct a partial summary: {"key_claims": ["<first 300 chars of response>"], "key_quotes": [], "relevance": "low", "confidence": 0.2, "source_type": "other", "deeper_question": null}.
3. Empty or errored: Fall back to direct read of the source via curl | head -100. Produce a low-confidence summary manually from what you can see.

5b. Recurse on deeper questions

If a sub-agent returns a non-null deeper_question AND confidence < 0.5:

1. Dispatch another sub-agent with the narrower question, referencing the same shared-state key.
2. Merge the answer into the existing summary (append new claims, update confidence).

Hard cap: recursion depth = 3. That's: initial dispatch → 1st recursion → 2nd recursion. After depth 3, accept whatever you have. If you find yourself wanting depth 4, your original question was probably too vague — go back to Step 1 and narrow it.

6. Store summaries and dispatch synthesis sub-agent

After all per-source summaries are collected, store them together:

shared_state set key="synthesis.<topic>.summaries" value="<JSON array of all summaries>"

Then dispatch a synthesis sub-agent to compose the final answer:

sub_agent: You are synthesizing research from multiple sources into a composed answer.

The per-source summaries are stored in shared state under key "synthesis.<topic>.summaries".
Read them with: shared_state get key="synthesis.<topic>.summaries"

Research question: <your single-sentence question from step 1>

Compose a synthesis that:
1. Identifies areas of AGREEMENT across sources
2. Identifies areas of DISAGREEMENT or tension
3. Notes any gaps — important aspects of the question that no source addressed
4. Weighs claims by source confidence and relevance

Reply with ONLY a JSON object (no markdown fences, no prose):
{
  "answer": "3-5 paragraph composed answer to the research question",
  "consensus": ["claims that multiple sources agree on"],
  "disagreements": ["claims where sources conflict, with attribution"],
  "gaps": ["aspects of the question not covered by any source"],
  "confidence": 0.0-1.0,
  "source_count": <number of sources that contributed>
}