Mike Swanson
a242797908
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>
2.0 KiB
name, description, metadata
| name | description | metadata | ||
|---|---|---|---|---|
| feedback_interview_ai_read_docs | 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. |
|
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/*.mdand~/.grok/README.md(andgrok inspect/grok models/grok <cmd> --helpfor 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.