better-search v1.0.1 + better-search-research v1.0.1 — alias fix, trigger rule, hash-suffix note, loop terminology, Claude-reviewed

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 `<question>`:
+
+```bash
+research -s better-search-research chat -q "<question>" -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: <sid> (reference only — do not --resume; re-dispatch for follow-ups)
+   ```
+
+   Plus the expected output path: `~/workspace/research/results/<date>-<slug>.md`
+   (filename may have a `-<hash>` 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/<YYYY-MM-DD>-<slug>.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-<sid>.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.