deep-research-synthesizer

name	deep-research-synthesizer
description	Given outputs from 5 research sub-agents (time-sliced or partitioned), validate and synthesize them into a coherent, citation-backed Markdown deep research report with deduplication, contradiction handling, and explicit debug visibility when inputs are missing or malformed.
license	MIT
compatibility	Framework-agnostic; assumes you can run 5 sub-agents and collect their text outputs (Markdown with a JSON packet header recommended).
metadata	{"author":"github.com/anthony-maio","version":"1.0"}

Deep Research Synthesizer

Use this skill when you have five sub-agent research results and need to produce a single high-quality Markdown report that:

• answers the user’s question directly
• preserves evidence + citations
• removes duplication
• flags contradictions and gaps
• never “silently fails” when one agent output is missing or malformed

This skill is designed to fix a common anti-pattern: a coordinator prompts 5 agents, then tries to “just synthesize” without a contract, validation, or observability.

---

Inputs expected (minimum)

1. user_question — the user’s original question (verbatim)

2. agent_outputs[5] — one output per agent.
   Each output MUST follow the Research Packet Contract (see references/AGENT_PACKET_CONTRACT.md).

If you cannot guarantee the contract, run scripts/validate_packets.py and repair nonconforming outputs before synthesis.

---

The 5-agent pattern that works

Step 1 — Partition the work (pick ONE strategy)

Strategy A: Time slicing (good for “what happened” / “how it evolved”)

• Agent 1: earliest timeframe
• Agent 2: next window
• …
• Agent 5: most recent window + “what changed recently”

Strategy B: Source slicing (good for broad topics)

• Agent 1: primary sources / official docs
• Agent 2: academic papers / standards
• Agent 3: practitioner writeups
• Agent 4: competing viewpoints / critiques
• Agent 5: synthesis + “what you should do” recommendations

Strategy C: Sub-question slicing

• Agent 1: definitions / scope
• Agent 2: current state
• Agent 3: failure modes / risks
• Agent 4: options + tradeoffs
• Agent 5: recommendations + decision framework

Step 2 — Enforce the Research Packet Contract

Every agent must output:

• a machine-parseable JSON “packet header”
• a short narrative
• a “Run Log” with searches + errors

Contract details: references/AGENT_PACKET_CONTRACT.md.

Step 3 — Validate before you synthesize

Run:

python scripts/validate_packets.py --in packets/

Fix failures immediately:

• missing sources
• missing claims/evidence mapping
• missing run logs
• malformed JSON

Step 4 — Normalize + deduplicate

Use:

python scripts/merge_packets.py --in packets/ --out merged.json

Then synthesize using the report template:

• references/REPORT_TEMPLATE.md
• include contradictions + gaps explicitly

Step 5 — Synthesize the final report (Markdown)

Write the report in this order:

1. Executive Summary (5–10 bullets)
2. Direct Answer (2–6 paragraphs)
3. Key Findings (grouped, deduped)
4. Evidence & Citations (trace claims → sources)
5. Contradictions / Uncertainties (what doesn’t match)
6. Recommendations (actionable, prioritized)
7. Appendix
   • per-agent “Run Log”
   • per-agent “Raw Findings” (optional)

Step 6 — QA checklist (do not skip)

Use references/QA_CHECKLIST.md.

If you can’t pass the checklist due to missing info, output a partial report and explicitly list:

• which agents failed
• what is missing
• what follow-up tasks would resolve it

---

Failure-handling requirements (what stops “constant failures”)

1) Never hide missing agent outputs

If any agent output is missing/empty:

• produce the report anyway
• mark the missing agent as “NO DATA”
• do not invent what it “would have found”

2) Surface tool errors verbatim

If an agent hit a tool error (HTTP, MCP, API):

• carry the raw error into the appendix
• summarize the impact in “Limitations”

3) Preserve traceability

Every major claim must have:

• source id(s)
• agent id
• confidence

This avoids “big report looks plausible but can’t be debugged.”

---

Files in this skill

References

• references/AGENT_PACKET_CONTRACT.md — required output format for sub-agents
• references/REPORT_TEMPLATE.md — Markdown structure + guidance
• references/QA_CHECKLIST.md — deterministic quality gates
• references/FAILURE_MODES.md — common causes of synthesis failure + mitigations

Scripts

• scripts/validate_packets.py — validates packet conformance and prints actionable errors
• scripts/merge_packets.py — merges packets into a single normalized JSON file
• scripts/render_report_skeleton.py — generates a Markdown skeleton from merged JSON