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.2.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. Cap is tight on purpose — if you find yourself writing more than 5, the question itself is under-specified and the right move is to push back to the operator, not interrogate them.

**Limits:**
- **Default cap: 3 questions.** Most well-formed questions need 0–3.
- **Hard cap: 5 questions.** Only if the question has multiple high-stakes branches that genuinely change the research strategy.
- **Abort at 6+:** If you think you need more than 5, 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 6+ 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
- Output line 2+: the research agent's condensed answer
- 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
```

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

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

Relay the research agent's actual response. Do not paraphrase or summarize. If the response is long, chunk it. The research agent already condensed — don't re-condense.

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

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