deep-research

Files (8)

• SKILL.md
• evals.json · evals/
• credibility-tiers.md · references/
• notebooklm-workflow.md · references/
• report-template.md · references/
• trusted-creators.yaml · references/
• gemini_deep_research.py · scripts/
• grok_xsearch.py · scripts/

SKILL.md (first lines)

# Deep Research

> **Drift-prone.** This skill orchestrates external CLIs (`gh`, `notebooklm`, `yt-dlp`) and optional MCPs (Reddit/X). Tool names, quotas, and result shapes change. Treat the platform arms as best-effort, design for graceful degradation, and never promise coverage you can't verify.

Multi-platform research with explicit disagreement surfacing. Inherits the parallel-agent + credibility-tier structure from [ahrav/Gossip-rs/deeper-research](https://github.com/ahrav/Gossip-rs/blob/main/.claude/skills/deeper-research/SKILL.md) and the NotebookLM-as-RAG arm from [manfromtunis/melek-skills/deep-research](https://github.com/manfromtunis/melek-skills/blob/main/deep-research/skill.md), with three additions specific to this skill: triage routing by topic-volatility, two-hop trust expansion to surface unknown-but-important voices, and a required Disagreement Ledger to prevent synthesis from papering over real conflict.

## When to activate

- Explicit: "deep research X", "deep dive into X", "research X thoroughly", "/deep-research"
- Implicit but high-confidence: "what's the state of X", "is there prior art for X", "compare X vs Y", "what are people saying about X", "investigate X", "due diligence on X", "competitive landscape for X"
- Coding-flavored: "has anyone built X already", "what libraries exist for X", "what's the canonical way to do X in 2026"

If the question would benefit from multi-source synthesis with citations, activate even if the user didn't explicitly request "research." Single-platform search (just WebSearch, just a `gh` query) is the wrong response when the user needs grounded confidence across sources.

## What each arm is FOR (purpose-first, not mechanic-first)

Each arm answers a fundamentally different research question. Don't confuse them — using Reddit when you needed documentation, or web search when you needed sentiment, produces bad reports.

| Arm | The question it answers | Why other arms can't |
|---|---|---|
| **Web** (Exa / Firecrawl / WebSearch) | "What does the static published record say?" — documentation, blogs, news, official posts | Slow to capture community execution reality; misses what people *think* |
| **GitHub** | "Has this been built? How does the real implementation work?" — repos as ground truth for what code exists | READMEs lie / oversell. **For reputable-looking repos, READ THE SOURCE.** That's where execution reality lives. |
| **Reddit + X** | "How are practitioners actually deploying this — AND what do they think of it?" — **deployment intelligence** (configs, prompts, workflows, war stories shared in threads) + **sentiment** (hype vs real, what people switched from/back to) | GitHub captures *codified* execution; Reddit/X capture the *unwritten* execution intelligence — the CLAUDE.md someone posted, the hook recipe in a comment, the "after 6 months of using X, here's what works" thread |
| **NotebookLM-YouTube** | "What have specific creators said in long-form (multi-hour) content?" — transcript-grounded RAG over videos/podcasts | In-context reading can hold ~2 videos max; this scales to 30+ with grounded retrieval |
| **Gemini Deep Research** | "What's the macro landscape with full provenance?" — multi-hop autonomous synthesis across 80–160 sources | Single-arm searches can't run their own follow-up loops |

## The five things this skill does that generic web-search doesn't

1. **Triage routes the query** — coding questions hit GitHub first; bleeding-edge AI hits social first; stable topics hit web/academic first. The routing exists because the *same* query "what's new in X" needs different platforms depending on what X is.
2. **GitHub prior-art is a first-class arm with source-code inspection** — for coding queries, the skill scans `gh search repos/code` AND, for repos that look reputable (stars, recent commits, real maintainers), reads the actual source code — not just READMEs. READMEs market; source code reveals.
3. **Sentiment + deployment intelligence from community channels** — Reddit and X aren't just "more sources." They serve two jobs no other arm can: (a) telling you what people actually *think* (hype vs real, what they switched from/back to), and (b) capturing the *unwritten* execution intelligence — the configs, prompts, hooks, and "here's my setup" recipes that practitioners share in threads but never push to a repo.
4. **Two-hop trust expansion** — the trusted-creator allowlist is a *kernel*, not a boundary. If `karpathy` quote-tweets an unknown account, that account is included with a `provisional` tag. Trust propagates one hop via human endorsement, with the chain preserved in output.
5. **Disagreement Ledger is required** — synthesis must enumerate factual claims where sources conflict, name both, and refuse to resolve. Coherent-but-misleading reports are the failure mode; this fights it directly.

## Workflow at a glance

```
Phase 0  Triage             classify query → routing flags
Phase 1  Decompose          3–5 sub-questions, tag platforms per Q
Phase 2  Fan-out (parallel) Web + GitHub + Reddit + X + NotebookLM-YouTube  ← subagents
Phase 3  Reputation gate    pre-filter blocklist, classify each source: trusted | provisional | unverified
Phase 4  Deep read          scrape top-K trusted/provisional; load long-form into NotebookLM
Phase 5  Adversarial review Contrarian Searcher + Devil's Advocate    ← subagents
Phase 6  Synthesize         report with Disagreement Ledger + Prior Art + NotebookLM ID
Phase 7  Persist            save report; notebook stays for follow-up querying
```

Wall-clock target: 8–12 minutes for a substantive query. If the user wants a quick scan, tell them to use plain WebSearch instead — this skill is for questions worth that time.

---

## Phase 0 — Triage

Before decomposing, classify the query along two axes:

**Topic-volatility:**
- **bleeding_edge** — query is about something <12 months old, fast-moving (a new model, a new tool, a new approach). Community signal (Reddit/X/HN) leads.
- **stable** — query is about something established (history, market, science, well-known tech). Web/academic leads.

**Coding-flavor:**
- **coding=true** — query is about libraries, frameworks, implementations, or "has X been built." Forces GitHub arm on.
- **coding=false** — query is about ideas, markets, people, policy.

State the classification explicitly to the user before fan-out: "Triaging this as `bleeding_edge + coding=true` — GitHub arm running first, then social, then web." This makes the routing auditable and gives the user a chance to redirect.

Routing rules (defaults; user can override):

| Triage | GitHub | Reddit/X | Web | NotebookLM-YT |
|---|---|---|---|---|
| `bleeding_edge + coding=true` | priority 1 | priority 2 | priority 3 | priority 3 |
| `bleeding_edge + coding=false` | skip | priority 1 | priority 2 | priority 2 |
| `stable + coding=true` | priority 2 | optional | priority 1 | priority 2 |
| `stable + coding=false` | skip | optional | priority 1 | priority 1 |

`priority 1/2/3` controls source-count budget. `optional` means run only if user asks or sub-question explicitly needs community signal.

---

## Phase 1 — Decompose

Break the topic into **3–5 sub-questions**. Each sub-question must:
- Be answerable from concrete sources (not "what's the meaning of X")
- Tag which arms it most needs (web / github / social / nlm)
- Be diverse — don't ask the same question five ways

Example (query: "current state of multi-agent deep-research systems for Claude Code, open-source"):
1. What open-source multi-agent research skills exist for Claude Code? **[github, web]**
2. What architectures do they use — orchestrator-worker, debate, ReAct? **[web, github]**
3. What benchmarks (GAIA, HLE) measure their performance? **[web, nlm]**
4. What are practitioners saying about strengths/weaknesses on Reddit/X? **[social]**
5. What does Anthropic's own multi-agent research pattern document recommend? **[web]**

Output Phase 1 to the user. Lets them redirect before you burn compute.

---

## Phase 2 — Parallel platform fan-out

**Spawn one subagent per active platform arm via the Agent tool.** Each arm runs independently — no shared state, no waiting on each other. Each gets a hard 90-second wall-clock budget and must return a structured payload:

```json
{
  "arm": "github",
  "status": "ok" | "degraded" | "failed",
  "sources": [{"url": "...", "title": "...", "snippet": "...", "platform_metadata": {...}}],
  "missing": "what we couldn't get and why"
}
```

`status: degraded` means partial results returned; `failed` means nothing usable. Synthesis must explicitly list which arms degraded in the report metadata.

### Web arm
- Tool: WebSearch + WebFetch
- Discover via 2–3 keyword variations of each sub-question
- Output: ~5–10 URLs per sub-question, with snippets

### GitHub arm (if `coding=true`)
- Tool: Bash → `gh search repos <topic> --sort stars --limit 15` and `gh search code <topic> --limit 10`
- For top 3–5 repos by stars + recency: fetch README via `gh api repos/<owner>/<name>/readme`

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness