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

---
name: better-search-research
description: 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.
version: 1.0.1
author: Hermes Agent
metadata:
  hermes:
    tags: [research, search, web, methodology, medium-depth]
    related_skills: [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:

```yaml
---
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`.