deep-research-synthesizer

Files (10)

• PROVENANCE.json
• REGISTRY.json
• SKILL.md
• AGENT_PACKET_CONTRACT.md · references/
• FAILURE_MODES.md · references/
• QA_CHECKLIST.md · references/
• REPORT_TEMPLATE.md · references/
• merge_packets.py · scripts/
• render_report_skeleton.py · scripts/
• validate_packets.py · scripts/

SKILL.md (first lines)

# 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:

```bash
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:
```bash
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

From anthony-maio/synthesis-skills, MIT.

More from anthony-maio/synthesis-skills