hermes-skills/deep-research/SKILL.md

---
name: deep-research
description: Dispatch exhaustive deep web research to the research profile. Triggered by "deep research", "ask web", or "research this". The research profile runs with the deep-web-research skill loaded — six-move flow, external ledger, mechanical saturation, disconfirmation, condensation from disk.
version: 2.3.0
author: Hermes Agent
license: MIT
platforms: [linux]
metadata:
  hermes:
    tags: [research, deep-research, delegation, web-search, scraping]
    related_skills: [ask-hermes, ask-claude, ask-dev, deep-web-research, writing-plans]
---

# deep-research — Exhaustive Web Research Delegation

## Overview

Dispatches a research question to the research profile, which runs with the `deep-web-research` skill loaded. The research agent does exhaustive, trail-following research — any tool, any trail, no rush — then condenses everything into a tight, concrete, evidence-backed answer. This agent just relays the result.

See `references/design-rationale.md` for the v2.0 architecture decisions and Claude validation findings.

**Trigger phrases:** "deep research", "ask web", "research this", "deep dive on", "exhaustive research on"

## Clarifying Questions (Before Dispatch)

If the operator's question is ambiguous enough that the research agent would waste the first ~20 turns guessing, ask clarifying questions BEFORE dispatching. The user wants maximum clarity — err on the side of asking.

**Limits:**
- **Default cap: 5 questions.** Most well-formed questions need 0–5.
- **Hard cap: 10 questions.** For complex, multi-branch research where precision matters.
- **Abort at 11+:** If you think you need more than 10, the question is under-specified. Stop and tell the operator: "This question has too many branches to dispatch cleanly. Can you narrow it to [specific scope]?" Do NOT fire 11+ questions.

**When to ask vs. when to dispatch:**
- Ask when the answer would change the research strategy (e.g., "Are you researching a person, a company, or a topic?" — different toolkits).
- Do NOT ask when the research agent can sensibly find out (e.g., "What year did X happen?" — the research will find it).
- Do NOT ask to delay dispatching. Asking is a cost, not a hedge.

**Multi-turn narrowing:** If after 1–2 rounds of clarifying questions the scope is still unclear, abandon the dispatch and ask the operator to rewrite the question with the scope made explicit. Do not loop.

## Command

```
hermes -p research -s deep-web-research chat -q "<question>" -Q --max-turns 600 --yolo
```

- Output line 1: `session_id: <id>` — capture this
- The research agent writes the condensed answer to `~/workspace/research/results/<YYYY-MM-DD>-<slug>.md`
- Hold the session_id for follow-up questions

**Subsequent asks (resume the session):**
```
hermes -p research -s deep-web-research chat --resume <session_id> -q "<follow-up>" -Q --max-turns 600 --yolo
```

## Delivery Method (MANDATORY)

**File-only delivery.** The research agent writes the full condensed answer to a markdown file and reports the path. Nothing is relayed inline.

- **Path:** `~/workspace/research/results/<YYYY-MM-DD>-<slug>.md`
- **Slug:** derived from the question (e.g., `minimax-m3-temperature-support`)
- **Format:** YAML frontmatter (question, date, sources, confidence) + markdown body with structured findings
- **After dispatch:** report the session_id and the expected output path to the user
- **When user asks for results:** use `session_search` on the research profile with the captured session_id, then relay the path — the user reads the file directly

The file is the single source of truth. Do not inline the research answer — it's always lossy for 100+ turn sessions.

## Post-Dispatch Behavior (MANDATORY)

**After dispatching, continue working with the user. Do NOT poll, wait, or check for results unless the user explicitly asks.**

- The research runs as a background process. It will complete on its own.
- Do NOT call `session_search` on the research session to check progress.
- Do NOT call `process wait` or `process poll` on the background process.
- Do NOT proactively surface results when the background process completes.
- **Only check for results when the user explicitly asks** (e.g., "what did the research find?", "is it done?", "show me the results").
- When the user asks, use `session_search` on the research profile with the captured session_id to confirm completion, then report the file path: `~/workspace/research/results/<date>-<slug>.md`. Do NOT inline the answer — the file is the source of truth.

The session_id is captured from output line 1 and held in conversation context for follow-up questions and result retrieval. No state file needed.

## What the Research Agent Does

The `deep-web-research` skill on the research profile enforces:

0. **Analyze & Strategize** — analyze the question, select tools from the arsenal, write strategy to ledger
1. **Decompose** — break the question into sub-questions with time classifications
2. **Landscape Pass** — shallow sweep, identify key sources and terms
3. **Deep-Dive** — 3+ search angles per sub-question, full-page reads, citation trails, depth-first
4. **Disconfirmation** — actively hunt for contradiction and outdated claims
5. **Condensation** — read the external findings ledger from disk, synthesize into a concrete answer

The research agent writes all findings to `/tmp/research-<sid>.md` (external ledger) and uses a phase gate file to enforce completion before condensing. Mechanical saturation checks (`grep -c`) prevent endless searching. Re-strategize checkpoints after Move 2 and every ~10 findings during Move 3 enable mid-research pivots.

## Tool Selection Strategy

The research agent must determine the best tools for each research type — not use a fixed set. Analyze the question and select from the full arsenal:

| Research Type | Primary Tools | Secondary Tools |
|---|---|---|
| **Person/identity** | SearXNG (people search engines, social media), web scraping (full pages) | Browser (dynamic sites), Python (data enrichment) |
| **Email/phone** | SearXNG (breach databases, public records), web scraping | Browser (captcha-walled sites), Python (pattern analysis) |
| **Software/tech** | SearXNG (GitHub, docs, PyPI/npm), web scraping (changelogs, issues) | Terminal (live version checks), Browser (interactive docs) |
| **Politics/news** | SearXNG (news category, multiple engines), web scraping (primary sources) | Browser (paywalled articles), Python (timeline analysis) |
| **AI/ML** | SearXNG (arxiv, papers, HuggingFace), web scraping (model cards, benchmarks) | Terminal (live API probes), Python (data analysis) |
| **General topic** | SearXNG (general + news + scholarly), web scraping (authoritative sources) | Browser (interactive content), Python (synthesis) |

**Tool selection rules:**
- Always use multiple SearXNG engines per search — never rely on a single engine
- For any claim about a live system, run a terminal probe (curl, ping, API call) — don't just search
- For version-sensitive claims, check at least 2 independent sources (docs + GitHub + PyPI)
- For paywalled or JavaScript-heavy content, use the browser tool
- For data that needs aggregation or analysis, use Python in the terminal
- Docker-based tools (SearXNG, Playwright) are available and should be used when appropriate
- The research agent has full terminal, file, web, browser, and Python access — use all of them

## When to Use

- User says "deep research", "ask web", "research this", "deep dive on"
- Question requires exhaustive multi-source investigation
- User wants current, verified, cross-referenced information
- Phone number lookup, person research, topic investigation, fact verification

## When NOT to Use

- Simple factual question (capital of France, current time)
- Question I can answer from a single search
- Task that needs my exact context state
- User explicitly says "quick search" or "just look it up"

## Relay Rule

Do NOT relay the research agent's response inline. The file at `~/workspace/research/results/<date>-<slug>.md` is the single source of truth. When the user asks for results, report the file path and let them read it directly. If the user asks for a specific finding, you may extract that one section from the file — but never inline the full answer.

## Spot-check Rule

The research agent self-reports are not verified fact. If it claims a file write, `read_file` the path to confirm. If it claims a specific finding, spot-check the source URL.

## Session Persistence

**HARD RULE: Same topic = resume. New topic = new session.**

- **Same topic / same line of research:** Always `--resume <session_id>`. Capture session_id from output line 1. Every follow-up in the same line of research MUST use `--resume <session_id>`. Starting fresh discards the research context and wastes turns.
- **New topic / new line of research:** Start a fresh session. Do NOT resume an unrelated session — the research context is polluted with the old topic and will produce confused results.

## Common Pitfalls

1. **Profile flag required.** Always use `-p research`. The sticky default may be general.
2. **Skill flag required.** Always use `-s deep-web-research`. Without it, the research agent runs in normal mode without the methodology.
3. **--yolo is required.** The research agent runs headless. Without it, approval prompts fail closed.
4. **600 turns is the ceiling, not the target.** The research agent should condense well before 600. Hitting the ceiling means it failed to condense. The operator's standing rule: 600 is a safety net, not a budget — "I just want a safety net. I would even be okay with 600 as a catch. I mostly want the job done right. Not concerned with time or tokens." Apply 600 for any plan-building, research, or evidence-based work; default to lower only for short factual lookups.
5. **Don't re-condense.** The research agent already produced a condensed answer. Relay it, don't summarize it further.
6. **Don't do the research yourself.** If the user triggers deep research, dispatch it. Don't run a few searches and call it done. This is the #1 failure mode: the agent runs 2-3 `mcp_searxng_searxng_web_search` calls, gets empty results, and gives up. That's not deep research — that's a casual lookup. If you catch yourself typing `mcp_searxng_searxng_web_search` for a deep research request, STOP. You're doing it wrong. Dispatch to the research profile.
7. **The methodology skill lives on the research profile.** `deep-web-research` is at `~/.hermes/profiles/research/skills/research/deep-web-research/SKILL.md`. It does NOT exist on the general profile. Don't search for it here — it won't be found. The general profile only has this delegation skill.
8. **Dispatcher/methodology coordination is a two-skill contract.** This skill (the dispatcher) caps clarifying questions at 5 default / 10 max and aborts the dispatch if the question is under-specified. The `deep-web-research` methodology skill (on the research profile) handles the same problem differently because it's headless — it can't ask the operator, so it aborts with a structured under-specification report naming the plausible interpretations. When updating one, update the other to match. Drift between the two causes the dispatcher to think the question is dispatchable while the methodology aborts it, or vice versa — both waste turns.

## Pre-Dispatch Reasoning Check (MANDATORY)

Before EVERY deep research dispatch, set the research profile's reasoning_effort to `max`. This is a hard gate — do not dispatch without it.

```
hermes -p research config set agent.reasoning_effort max
```

`max` is the highest effort setting universally supported by all models. No model-specific table needed. If the model changes to one that supports `xhigh`, the user will set it in config — the pre-dispatch check just ensures it's at `max` minimum.

## Research → Validate → Fix Pipeline

When the user wants a research deliverable validated and corrected, use this three-stage pipeline:

```
Stage 1: Deep research → produces <plan>.md
Stage 2: Ask-hermes validation → produces <plan>_validation.md
Stage 3: Deep research fix pass → updates <plan>.md with corrections
```

**Operational guide (exact prompts, session handling, failure modes):** `references/research-validate-fix.md`. The summary below is the quick reference; the reference file is the deep version.

**Stage 2 prompt template** (dispatch to `ask-hermes`):
```
Validate the plan at <path>. Read the full file first.
CRITICAL: Use mcp_searxng_searxng_web_search for EVERY claim and cite the source URL.
Validate: model versions, license claims, VRAM claims, tool availability, new tools since plan was written, hardware benchmarks.
For each finding: CLAIM → VERIFIED/CONTRADICTED/UPDATED → source URL → recommended fix.
Save to <path>_validation.md.
```

**Stage 3 prompt template** (resume the research session):
```
Read the validation report at <path>_validation.md. Read the current plan at <path>.md.
Apply ALL fixes from the validation report. Keep all existing content. Make targeted edits only. Do NOT rewrite the whole plan.
```

**Key rules:**
- Stage 2 and 3 can run in parallel with other work (both are background processes).
- Stage 3 MUST use `--resume <session_id>` from Stage 1 — same research session, same context.
- The validation agent (Stage 2) is a fresh `ask-hermes` session each time — no resume needed.
- If Stage 2 finds CRITICAL omissions, Stage 3 must address them before the plan is considered complete.
- Operator must apply the **Disagreement Scan** (see `ask-hermes` skill) to Stage 2 findings before applying them in Stage 3 — peer findings are input, not commands.