hermes-skills/better-search-research/SKILL.md

name, description, version, author, metadata

name	description	version	author	metadata
better-search-research	Medium-depth web research methodology — 3-move flow (initial search → AI evaluation → condense), 3-loop cap, /tmp ledger, file-only delivery. Opt-in skill for the research profile.	1.0.1	Hermes Agent	hermes tags related_skills research search web methodology medium-depth deep-web-research searxng-smart-search

better-search-research — Medium-Depth Web Research Methodology

Loaded explicitly via -s better-search-research. Not loaded during normal interactive use of the research profile. This skill enforces a 3-move research flow with a hard 3-loop cap.

§1 Overview

This skill performs a 3-move research flow:

1. Move 1: Initial Search — 2-3 SearXNG searches with different framings, read top results, write structured summary to /tmp/better-<sid>.md.
2. Move 2: AI Evaluation + Refine — Read the ledger from disk, self-evaluate for gaps/contradictions/shallowness, optionally run 1-2 refinement searches.
3. Move 3: Condense + Deliver — Read full ledger, write final answer to ~/workspace/research/results/<YYYY-MM-DD>-<slug>.md with 6-field frontmatter.

Hard loop cap: 3 (1 initial search + up to 2 refinements). The cap is enforced by the ledger — at most 1 ## Search block and 2 ## Refinement blocks. No saturation-based continuation. No --resume — every dispatch is a fresh session with a new ledger and a new 3-loop budget.

Total budget: 50 turns. The 3-loop cap is the real limit; 50 turns is a safety net. If the agent hits 50, deliver partial results with a note.

Ledger: /tmp/better-<sid>.md — a flat structured file (no credibility tiers, no phase gate). The ledger forces a re-read from disk at each move so details that scrolled out of context are not lost.

§2 Move 1: Initial Search

Turns 1-5. Gather initial evidence.

1. Run 2-3 SearXNG searches with different framings:
   • Different SearXNG categories (e.g., general vs it,science)
   • Different keywords (broad vs. specific)
   • Different time-range filters (year for established facts, week for recent news)
   • At least one search targeted at the most authoritative source (official docs, GitHub, peer-reviewed pages)
2. Read top 1-3 results per search with mcp_searxng_web_url_read.
3. Write a structured summary to /tmp/better-<sid>.md:

## Question
<verbatim question>

## Search 1: <query>
- Source: <url>
- Key facts: <bullet list>
- Date: <YYYY-MM-DD if available>

## Search 2: <query>
...

No credibility tier — the ledger is just URL + key facts + date. Tier judgment happens in the body, not the ledger.

SearXNG error handling: If mcp_searxng_searxng_web_search returns 0 results or errors, count it as one search and either retry once with a different framing or proceed to Move 3 with what was found. Don't burn a refinement slot on retries.

Filesystem assumption: mkdir -p ~/workspace/research/results and all ~ paths in Move 3 assume the research profile shares the same filesystem as the dispatcher's profile. This is true for all profiles on this machine.

/tmp cleanup: The ledger file is ephemeral — /tmp is cleared on reboot. No manual cleanup needed.

§3 Move 2: AI Evaluation + Refine

Turns 6-15. Evaluate what was found and fill gaps.

1. Read /tmp/better-<sid>.md from disk.

2. Self-evaluate using these criteria (write the eval to the ledger):

   • Coverage: Are major angles covered? (Yes → continue; No → refine)
   • Recency: Is the info current? If question is time-sensitive, are there 2025-2026 sources?
   • Specificity: Concrete numbers/dates/names? Or vague generalities?
   • Contradictions: Do sources disagree?
   • Source quality: Mostly primary/official, or just aggregators?

3. IF gaps → write ## Refinement <N>: <new query> to ledger, run 1-2 more searches, append findings.

4. Hard cap: 2 refinements total. Track count in the ledger.

5. IF no gaps (or cap hit) → proceed to Move 3.

Ledger format for refinements:

## Refinement 1: <new query>
- Source: <url>
- Key facts: <bullet list>
- Date: <YYYY-MM-DD if available>

§4 Move 3: Condense + Deliver

Turns 16-50. Synthesize and write the final answer.

1. Read full ledger from disk.
2. First, mkdir -p ~/workspace/research/results — without this, the write can fail silently on a fresh machine.
3. Determine the output filename:
   • Base: <YYYY-MM-DD>-<slug>.md where slug is derived from the question (e.g., current-python-version).
   • If <date>-<slug>.md already exists, append -<short-hash> derived from the session_id (e.g., 2026-07-07-current-python-version-a3f2c.md). Using the session_id (not the question text) ensures two parallel dispatches of the same question don't collide.
4. Write final answer with the 6-field frontmatter:

---
question: <verbatim>
date: <YYYY-MM-DD>
searches: <N total SearXNG queries issued>
refinements: <N refinement queries issued>   # 0 if no refinement happened
sources: <N unique sources cited in the answer>
confidence: high | medium | low
---

Confidence rule: high only when 2+ independent sources agree on the answer. medium when 1 strong source. low when the agent had to infer or the search was partial. No guessing "high" by default. Limitation: independence is judged subjectively by the agent — there's no mechanical way to distinguish "2 independent sources" from "1 source repeated in 2 places." For higher-stakes questions, dispatch deep-research instead.

Body: Lead with the answer, evidence-backed bullet points, sources section at end (URL + 1-line description, no credibility tier).

Write safety: If the file write fails for any reason (permissions, disk full, missing parent), print the full answer to stdout as fallback — never silently lose it.

5. Report file path to caller (this is the final stdout message from the research agent).

§5 Safety Boundaries

These persist across all turns — they are in the skill, not in fading context:

• Confined to /tmp. All file writes go to /tmp/. Never write outside /tmp except for the final result file in ~/workspace/research/results/.
• No self-provisioning. Never install software. No pip, npm, apt, docker, or any package manager. Use only what's already configured.
• No repeat searches. If you catch yourself searching the same thing twice, stop. That sub-question is saturated.
• Blacklist after 3 failures. If a URL returns an error 3 times, blacklist it and move on. Do not retry indefinitely.
• Local and free only. No internet-based paid services, no SaaS APIs with billing, no metered endpoints. Use any tool already configured that fits this rule.

§6 Cap-Hit Behavior

When the 3-loop cap is hit (1 initial search + 2 refinements used) without satisfaction:

1. Proceed directly to Move 3 — condense what you have.
2. In the result file body, add a note at the top:

   Note: Loop cap reached (3 loops / 1 initial + 2 refinements). Some angles may not be fully explored. For exhaustive coverage, re-dispatch with a refined question or use deep-research.

When the 50-turn ceiling is hit:

1. Deliver a partial answer to ~/workspace/research/results/<date>-<slug>.md with a header note: "incomplete — turn ceiling hit at Move N."
2. Operator can re-trigger the dispatcher with a refined question.

§7 See Also

• deep-web-research — exhaustive multi-source research with disconfirmation pass, phase gate, and 600-turn budget. Use when the question needs deep drilling, contradiction-hunting, or multi-sub-question decomposition.
• searxng-smart-search — single-shot SearXNG search with auto-category routing. Use for quick factual lookups that don't need evaluation or refinement.
• better-search (dispatcher) — the operator-facing skill that triggers this methodology. Installed on all profiles; delegates to the research profile via research -s better-search-research.