grok: fix xsearch (multi-agent web_search), pin grok-build, RTFM doc sweep

Root-caused the long-standing `ask-grok.sh xsearch` "no result (stopReason=)"
failure by reading Grok's bundled docs (~/.grok/docs/user-guide + README) instead
of probing:
- web_search runs a SEPARATE multi-agent model (grok-4.20-multi-agent), so the
  wrapper's blanket --no-subagents strangled it -> indefinite hang, 0 bytes. Scoped
  --no-subagents OFF xsearch; use --yolo (documented headless tool-run posture).
- xsearch prompt mandated X/Twitter search on every call (slow multi-agent) and the
  budget was 240s -> still timed out. Now web-primary (X only when relevant), 300s.
  Validated end-to-end through the wrapper: 23s, correct answer + 3 sources.

Model: pin -m grok-build (xAI flagship, 512k, the documented default) for the
reasoning modes (text/verify/review*) so quality is deterministic and not at the
mercy of the runtime default (this machine drifted to grok-composer-2.5-fast, a fast
Cursor coding model). xsearch + image/video keep the runtime default. Validated text
mode on grok-build (13s).

Doc accuracy (SKILL.md): corrected the model facts (default, the separate web_search
model, --effort unsupported on grok-build per supports_reasoning_effort:false);
documented the xsearch subagent exception. Fixed a stale in-script comment claiming
--rules/--disallowed-tools "tripped the CLI" (both are valid headless flags).

memory: add feedback_interview_ai_read_docs (read bundled docs / interview the model
before probing) + index; errorlog correction.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-16 19:14:59 -07:00
parent 58ecc5ad40
commit a242797908
5 changed files with 85 additions and 9 deletions

View File

@@ -0,0 +1,35 @@
---
name: feedback_interview_ai_read_docs
description: Before guessing or probing an external AI/CLI's command syntax or capabilities, READ its bundled docs and/or interview the model itself — probing wastes tokens and misleads.
metadata:
type: feedback
---
When you need to understand an external AI's or CLI tool's **command syntax or
capabilities**, do NOT blindly guess flags or run slow trial-and-error probes.
First **read its own bundled documentation**, and/or **interview the model
itself** (ask it to read its own docs and explain). The authoritative source is
almost always already on disk.
**Why:** repeated timed probing is expensive (each Grok run is 80-300s), gives
ambiguous signals, and is the exact "blindly guessing or probing" pattern Mike
has flagged. The docs answer the question directly and for free.
**Concrete example (the lesson):** the long-standing `ask-grok.sh xsearch`
"no result (stopReason=)" failure was root-caused not by probing but by reading
**`~/.grok/docs/user-guide/` (esp. `14-headless-mode.md`, `11-custom-models.md`,
`05-configuration.md`) and `~/.grok/README.md`**. They revealed: `web_search`
runs a SEPARATE multi-agent model (`grok-4.20-multi-agent`), so the wrapper's
blanket `--no-subagents` strangled it; the documented headless JSON schema is
`{text,stopReason,sessionId,requestId}`; and `--yolo` is the documented
tool-run posture. One confirmatory run, not a dozen.
**How to apply:**
- For the Grok CLI: read `~/.grok/docs/user-guide/*.md` and `~/.grok/README.md`
(and `grok inspect` / `grok models` / `grok <cmd> --help` for live truth)
before changing [[feedback_windows_quote_stripping]]-style wrapper internals.
- For any vendor CLI/API: locate its shipped docs/`--help`/OpenAPI first; treat
one targeted run as *confirmation* of a doc-derived hypothesis, not as the
discovery method.
- Interviewing the model (its text path) is valid even when a tool path is
broken — asking Grok doesn't require its web_search to work.