From 29556adb6ffdba61c2529913c36e0319f6df736c Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Mon, 6 Jul 2026 15:43:03 -0500 Subject: [PATCH] =?UTF-8?q?deep-research=20v2.2.0,=20deep-web-research=20v?= =?UTF-8?q?2.1.0=20=E2=80=94=20clarifying-question=20cap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both skills now have a hard cap on clarifying questions / scope ambiguity: - deep-research (general profile dispatcher): 3 questions default, 5 hard cap, abort at 6+. If the operator's question is under-specified, push back rather than fire 6+ questions. - deep-web-research (research profile methodology): headless, no operator to ask. Detects under-specified questions and aborts with a structured report naming the plausible interpretations, instead of dispatching with a guessed scope. This addresses the workshopping rule: 'up to 10 clarifying questions at start, with max clarity.' Consensus after peer review: 10 is too many, tighter cap forces prioritization. Abort at 6+ is the signal that the question itself is broken, not the agent's question-asking budget. --- deep-research/SKILL.md | 25 ++++++++++++++++++++++--- deep-web-research/SKILL.md | 36 +++++++++++++++++++++++++++++++++++- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/deep-research/SKILL.md b/deep-research/SKILL.md index d982aed..5f1e72e 100644 --- a/deep-research/SKILL.md +++ b/deep-research/SKILL.md @@ -1,14 +1,14 @@ --- 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.0.0 +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-dev, deep-web-research] + related_skills: [ask-hermes, ask-claude, ask-dev, deep-web-research, writing-plans] --- # deep-research — Exhaustive Web Research Delegation @@ -21,6 +21,22 @@ See `references/design-rationale.md` for the v2.0 architecture decisions and Cla **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 ``` @@ -83,7 +99,7 @@ The research agent self-reports are not verified fact. If it claims a file write 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. +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. @@ -108,6 +124,8 @@ Stage 2: Ask-hermes validation → produces _validation.md Stage 3: Deep research fix pass → updates .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 . Read the full file first. @@ -128,3 +146,4 @@ Apply ALL fixes from the validation report. Keep all existing content. Make targ - Stage 3 MUST use `--resume ` 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. diff --git a/deep-web-research/SKILL.md b/deep-web-research/SKILL.md index 08cd99c..b79310b 100644 --- a/deep-web-research/SKILL.md +++ b/deep-web-research/SKILL.md @@ -1,7 +1,7 @@ --- name: deep-web-research description: Exhaustive deep web research — six-move flow, external findings ledger, mechanical saturation check, disconfirmation, condensation from disk. Domain-aware tool selection with adaptive re-strategizing. Opt-in skill for the research profile. -version: 2.0.0 +version: 2.1.0 author: Hermes Agent --- @@ -102,6 +102,40 @@ that are immune to header ordering. confirmed by a human-authored source is still confirmable. Don't auto-cap confidence just because the tier is `osint`. +## Under-Specified Question Handling + +This skill runs headless — there is no operator to ask clarifying questions. If the question is ambiguous enough that any strategy would be a guess, **abort with a structured under-specification report instead of dispatching with a guessed scope.** + +**Detection triggers (any one is enough to abort):** +- The question references a person / org / project / model with no disambiguating context (multiple plausible referents, no narrowing clue in the prompt) +- The question asks "everything about X" with no scoping (time range, domain, angle) +- The question has 3+ mutually-exclusive branches and no signal which one is wanted +- The question uses vague hedges ("good", "best", "modern", "recent") with no concrete criterion + +**What to do instead of guessing:** +1. Do NOT start Move 0. Do NOT begin the ledger. +2. Write to stderr / final report: + + ``` + ## Aborted: Under-Specified Question + + The question "" has multiple plausible interpretations. + Cannot dispatch a research strategy without narrowing the scope. + + Possible interpretations: + - + - + - + + Ask the operator to clarify which one is intended, or rewrite the question with the scope made explicit. + ``` + +3. Exit cleanly. Do not fabricate findings, do not start Move 1. + +**Cap on auto-clarification attempts:** None. The skill does not interactively ask the operator. One dispatch, one answer (or one abort). The dispatcher (`deep-research` on the general profile) handles the operator-facing clarifying question loop before this skill is even loaded — see the "Clarifying Questions (Before Dispatch)" section in that skill. + +**Cap on output length when aborting:** Short. The whole point of the abort is to surface the problem fast. Five lines of possible interpretations is the ceiling. + ## Six-Move Research Flow ### Move 0: Analyze & Strategize