141 lines
8.1 KiB
Markdown
141 lines
8.1 KiB
Markdown
---
|
|
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 — five-move flow, external ledger, mechanical saturation, disconfirmation, condensation from disk.
|
|
version: 1.0.1
|
|
author: Hermes Agent
|
|
license: MIT
|
|
platforms: [linux]
|
|
metadata:
|
|
hermes:
|
|
tags: [research, deep-research, delegation, web-search, scraping]
|
|
related_skills: [ask-hermes, ask-dev, deep-web-research]
|
|
---
|
|
|
|
# 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.
|
|
|
|
**Trigger phrases:** "deep research", "ask web", "research this", "deep dive on", "exhaustive research on"
|
|
|
|
## Command
|
|
|
|
```
|
|
hermes -p research -s deep-web-research chat -q "<question>" -Q --max-turns 200 --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 200 --yolo
|
|
```
|
|
|
|
## What the Research Agent Does
|
|
|
|
The `deep-web-research` skill on the research profile enforces:
|
|
|
|
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.
|
|
|
|
## 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. **200 turns is the ceiling, not the target.** The research agent should condense well before 200. Hitting the ceiling means it failed to condense.
|
|
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. **`reasoning_effort: xhigh` breaks `glm-5.2:cloud`.** The research profile's default model (`glm-5.2:cloud` via `custom:ollama`) rejects `xhigh` — it only accepts `high`, `medium`, `low`, `max`, or `none`. If the dispatch fails with "HTTP 400: invalid reasoning value: 'xhigh'", check `~/.hermes/profiles/research/config.yaml` → `agent.reasoning_effort`. Set it to `max` (the highest level the model actually supports). Do NOT downgrade to `high` without asking the user — they explicitly want maximum reasoning effort. If the model changes to one that supports `xhigh`, revert to `xhigh`.
|
|
|
|
## Pre-Dispatch Reasoning Check (MANDATORY)
|
|
|
|
Before EVERY deep research dispatch, verify the research profile's reasoning_effort is set to the maximum the model supports. This is a hard gate — do not dispatch without checking.
|
|
|
|
```
|
|
# 1. Read the research profile's current model and reasoning_effort
|
|
grep -E "default:|reasoning_effort:" ~/.hermes/profiles/research/config.yaml
|
|
|
|
# 2. If reasoning_effort is NOT 'max' (or 'xhigh' for models that support it):
|
|
# - If model is glm-5.2:cloud → set to 'max' (xhigh rejected)
|
|
# - If model is deepseek-v4-pro:cloud → set to 'max' (xhigh rejected)
|
|
# - If model is minimax-m3:cloud → set to 'xhigh' (supports it)
|
|
# - If unsure what the model supports → set to 'max' (safe default)
|
|
|
|
# 3. Apply the fix if needed:
|
|
hermes -p research config set agent.reasoning_effort max
|
|
# OR for models that support xhigh:
|
|
hermes -p research config set agent.reasoning_effort xhigh
|
|
```
|
|
|
|
**Rule:** Always dispatch with the highest reasoning effort the model actually supports. Never silently downgrade. If the model changed and you don't know what it supports, test with `max` first (universally safer than `xhigh`).
|
|
|
|
## 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
|
|
```
|
|
|
|
**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.
|