--- 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-.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/-.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-.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-.md`: ``` ## Question ## Search 1: - Source: - Key facts: - Date: ## Search 2: ... ``` 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-.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 : ` 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: - Source: - Key facts: - Date: ``` ## §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: `-.md` where slug is derived from the question (e.g., `current-python-version`). - If `-.md` already exists, append `-` 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: date: searches: refinements: # 0 if no refinement happened sources: 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/-.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`.