better-search v1.0.1 + better-search-research v1.0.1 — alias fix, trigger rule, hash-suffix note, loop terminology, Claude-reviewed
This commit is contained in:
Hermes Agent
197
better-search-research/SKILL.md
Normal file
197
better-search-research/SKILL.md
Normal file
@@ -0,0 +1,197 @@
|
||||
---
|
||||
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`.
|
||||
Reference in New Issue
Block a user