diff --git a/better-search-research/SKILL.md b/better-search-research/SKILL.md new file mode 100644 index 0000000..9ae5149 --- /dev/null +++ b/better-search-research/SKILL.md @@ -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-.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`. diff --git a/better-search/SKILL.md b/better-search/SKILL.md new file mode 100644 index 0000000..21f9481 --- /dev/null +++ b/better-search/SKILL.md @@ -0,0 +1,166 @@ +--- +name: better-search +description: Medium-depth web research dispatcher — delegates to the research profile for a 3-move search flow (initial search → AI evaluation → condense). File-only delivery. Trigger phrases: "better search", "do a better search". +version: 1.0.1 +author: Hermes Agent +metadata: + hermes: + tags: [research, search, web, dispatcher, medium-depth] + related_skills: [deep-research, searxng-smart-search, ask-hermes] +--- + +# better-search — Medium-Depth Web Research Dispatcher + +## §1 Overview + +`better-search` is a dispatcher skill that delegates medium-depth web research +to the research profile. It sits between `searxng-smart-search` (single-shot, no +evaluation) and `deep-research` (200-turn, full disconfirmation pass). + +**Architecture:** Two-skill contract. This dispatcher is installed on all +profiles and owns trigger detection, optional clarifying questions (max 3), the +dispatch command, session-id capture, and the file-only delivery report. The +methodology `better-search-research` runs ONLY on the research profile and owns +the actual 3-loop flow. The dispatcher always delegates to the research profile +via `research -s better-search-research` — the dispatcher never runs +the research itself. + +**Trigger phrases:** `better search`, `do a better search`. These are the ONLY +phrases that fire this skill. Do NOT add `look into`, `find out`, `search again`, +or other ordinary English — they collide with normal agent tasks on dev/code +profiles. + +## §2 When to Use / When NOT to Use + +**TRIGGER RULE (absolute):** If the user says "better search for X" or "do a +better search for X", you MUST dispatch. No exceptions. Do NOT evaluate whether +the question is "worthy" of better-search — the operator already made that +decision by using the trigger phrase. The routing table below is for the +OPERATOR to decide which tool to ask for, not for you to second-guess. + +**Routing table (operator's responsibility, not the dispatcher's):** + +| Question shape | Tool | +|---|---| +| "What's the X for Y?" / single fact | Use SearXNG MCP directly | +| "Better search for X", "Do a better search for X" | `better-search` (this skill) | +| "Map the X landscape", "Exhaustive research on X", "OSINT: X" | `deep-research` | + +## §3 Command — RUN THIS EXACTLY, DO NOT QUESTION IT + +**This is your ONLY job when the user says "better search" or "do a better search."** +Run this command verbatim with the user's question substituted for ``: + +```bash +research -s better-search-research chat -q "" -Q --max-turns 50 --yolo +``` + +**`research` is a profile alias** (created by `hermes profile alias research`). +It is equivalent to `hermes -p research` but avoids the `-p` flag that some +models incorrectly believe doesn't exist. The alias is installed at +`~/.local/bin/research` and works from any directory. + +**Flag rationale:** +- `research` — profile alias, selects the research profile +- `-s better-search-research` — hardcoded methodology skill +- `-Q` — quiet mode, suppresses interactive prompts +- `--max-turns 50` — safety net (the 3-loop cap is the real limit, enforced by + the methodology's ledger) +- `--yolo` — required for headless one-shot dispatch; without it, approval + prompts fail closed + +**No pre-dispatch config write.** The research profile's `agent.reasoning_effort` +is already set appropriately. The dispatcher does NOT mutate the research +profile's config — that would be a persistent side-effect across all +research-profile sessions. + +## §4 Clarifying Questions (Max 3) + +Only ask clarifying questions if the question is ambiguous enough that the +research agent would burn 2 loops guessing. Default: 0 questions. Hard cap: 3. + +Routing decisions ("is this a single fact or a deep dive?") belong to the +operator, not the dispatcher. If the operator says "better search for X", trust +that they want the better-search flow — don't second-guess and suggest +`deep-research` or a direct MCP call. + +## §5 File-Only Delivery + +After dispatching: + +1. **Capture `session_id`** from the research agent's output (first line of + stdout). +2. **Report** the session_id with the explicit caveat: + + ``` + session_id: (reference only — do not --resume; re-dispatch for follow-ups) + ``` + + Plus the expected output path: `~/workspace/research/results/-.md` + (filename may have a `-` suffix if a same-day slug already exists). + +3. **Then return control to the operator.** Do NOT poll, do NOT check for + results, do NOT background, do NOT auto-deliver the answer inline. The + operator reads the result file when they want to. + +The research agent writes the result file to +`~/workspace/research/results/-.md`. The operator reads it +with `cat` or their preferred reader. + +## §6 No-Resume Rule + +**No `--resume`.** The dispatcher reports `session_id` for the operator's +reference only. Every follow-up question is a fresh dispatch with a new sid, new +`/tmp/better-.md` ledger, and a new 3-loop budget. The cap is provable only +because each dispatch is independent. + +**Trade-off:** The operator loses the research context between dispatches — if +iterative drilling on the same evidence matters, use `deep-research` instead +(which supports `--resume`). + +## §7 Common Pitfalls + +1. **Don't deep-research in a better-search call.** The methodology skill + enforces the 3-loop cap. Don't prompt around it with "do a deep dive" — use + `deep-research` instead. + +2. **`--yolo` is required.** Same as `deep-research`. Headless one-shot. Without + `--yolo`, approval prompts fail closed. + +3. **`--max-turns 50` is the safety net, not the budget.** 3 loops is the cap. + Hit 50 means Move 2/3 went long; the agent delivers partial results with a + note. + +4. **Don't poll, don't check, don't background.** The dispatcher returns control + to the operator immediately after capturing the session_id. It does NOT run + the research in the background, does NOT periodically check whether the + result file has appeared, and does NOT auto-deliver the result inline or to a + chat platform. + +5. **Max 3 clarifying questions (see §4).** Multi-part questions get condensed + into a single noun-phrase question or split into separate dispatches. + +6. **No `--resume`.** The dispatcher reports `session_id` for the operator's + reference only. Every follow-up question is a fresh dispatch with a new sid, + new ledger, and new 3-loop budget. + +7. **The 2 triggers (`better search`, `do a better search`) are the only phrases + that fire this skill.** Don't add `look into`, `find out`, `search again`, or + other ordinary English — they collide with normal agent tasks on dev/code + profiles. + +8. **Do NOT second-guess the dispatch command.** The command `research -s + better-search-research chat -q "..." -Q --max-turns 50 --yolo` is verified + and correct. `research` is a profile alias at `~/.local/bin/research` — it + works from any directory. Do NOT assume it doesn't exist and fall back to + doing the search yourself. The dispatcher's ONLY job is to run this command + and report the session_id — never substitute your own search. + +## §8 See Also + +- `deep-research` — exhaustive multi-source research with disconfirmation pass, + phase gate, and 600-turn budget. Use when the question needs deep drilling. +- `searxng-smart-search` — single-shot SearXNG search with auto-category routing. + Use for quick factual lookups. +- `ask-hermes` — persistent peer Hermes agent for delegated work. Use for + general-purpose delegation, not research-specific flows.