ragnar-pwninskjold/caveman-search

caveman-search

Research-backed answers in compressed caveman voice. Decompose research like Compound Engineering; render like Matt Pocock; always lead with the big truth.

What this does

1. Detects whether the question needs LOCAL repo research, EXTERNAL web research, or BOTH.
2. Runs a local-first escalation gate — skips web research when the repo already answers it.
3. Fans out to parallel research agents.
4. Optionally runs an adversarial verify pass (--verify).
5. Renders the result in caveman voice, big-truth-first.

Flags

• --verify (or --deep): run the adversarial verifier on each key recommendation.
• --hard: maximum voice compression (see voice spec).
• No flags: light-medium voice, no verifier.

Step 1 — Detect mode

Inspect the question and current context:

• Mentions "this/here/our code", repo file names, or "add X here" -> repo mode.
• Names external tech, asks "what should I use", greenfield, or "if I wanted to build" -> web mode.
• Both signals, or genuinely ambiguous -> both.
• Pure general-topic with no repo angle -> web only (do not waste a repo scan).

Also read the audience tier from the question. DEFAULT to builder and bias toward simple — recommend the simplest tool that clears the bar, not the most rigorous one. Escalate to expert ONLY on explicit signals: "ML team", "production-grade", "at scale", "I already use X", named low-level libraries, researcher-depth framing. Signals like "assume X is solved, I just care about Y" or "I want to ship" mean: stay simple, give one clear path. Pass the tier to the web researcher in Step 3.

Step 2 — Escalation gate (local-first)

If repo mode ran:

• Spawn caveman-repo-scout first (or as part of the parallel fan-out) and read its local_coverage.
• If local_coverage >= 3 AND the topic is NOT high-risk (auth, payments, data migration, external API integration) -> answer from local research, skip web.
• Otherwise escalate: also run web research.
• High-risk topics ALWAYS escalate to web, regardless of local_coverage.

Step 3 — Parallel fan-out

Dispatch the selected agents in a SINGLE message so they run concurrently (Task tool, one call per agent):

• repo mode -> tech-snacks:research:caveman-repo-scout
• web mode -> tech-snacks:research:caveman-web-researcher
• both -> both, in parallel.

Pass each agent the topic (cleaned of flags). Pass the web researcher the audience tier from Step 1 so it surfaces the right depth of tools (simple/builder = batteries-included; expert = composable stacks ok).

Step 4 — Verify pass (only if --verify)

Each caveman-web-researcher recommendation is already a self-contained claim. For each one, dispatch tech-snacks:research:caveman-verifier in parallel (one call per claim, single message). Reconcile:

• verdict holds -> keep, unmarked.
• verdict weakened -> keep with the verifier's correction folded in.
• verdict wrong -> drop it; if the verifier supplied a real answer, use that instead.

Step 5 — Render

Read these two files and follow them exactly:

• references/voice-spec.md — the voice TRANSFORM (not a description — apply it). Big Truth First is mandatory.
• references/output-format.md — the section skeleton.

The digest you got from the researchers is verbose. Do NOT echo its register. Transform it through the voice spec — drop articles/filler/hedging, force fragments, lead with the Big Truth. Then run the voice spec's pre-output check before sending: if sentences read full and smooth like a report, you drifted — rewrite them. Keep the researcher's per-job 2-3-option structure; do not re-expand it into a buffet.

Apply the Auto-Clarity Exception from the voice spec for any security warning, irreversible action, or ordered sequence.

Step 6 — Output

Emit the response per the output skeleton: big truth -> tools -> shape (if architectural) -> bottom line -> sources (if web mode). Annotate corrected claims inline if --verify ran.

Honesty rule

If research found nothing solid, say so terse and name the closest option plus its gap. Never invent confident-sounding tool names — in this voice a wrong claim reads as authoritative, which is the worst failure mode.