An always-on unknown-unknowns system for Claude Code. Scout converts unknown unknowns into known unknowns before you commit to an approach: the terms of art, taxonomies, canonical tools, named methods, and tribal knowledge of any domain - plus the questions you didn't know to ask.
The story of how it was designed: https://scout-with-ai.vercel.app (that's index.html in this repo)
curl -fsSL https://raw.githubusercontent.com/tripleyak/scout/master/install.sh | bashThen restart Claude Code (skills load at session start) and try:
/scout "web animation and motion design"
Requirements: Claude Code, python3, git.
Plenty of tools now package the eight techniques from Thariq Shihipar's field guide as skills (see Lineage - scout borrows from it too). Four things here are, as far as I can tell, not in any of them:
- Blind multi-lens fan-out. The sweep is several agents that cannot see each other, each owning one way of seeing a domain - vocabulary, tooling, tribal knowledge, your local repo. One searcher finds what it searches for; unknown unknowns hide in the angles you didn't take. And redundancy is worse than useless here: N agents with the same prior produce unanimous, confident, wrong answers.
- Briefs are graded, not self-certified. A fresh-context verifier grades every filed brief against an external rubric with a bias toward FAIL. Required failures send it back. The agent that wrote the brief never gets to approve it.
- An always-on tripwire. A regex hook watches every prompt for uncertainty phrasing and new-territory signals, so scout can offer itself on the prompt where you didn't know to ask for it. Cheap trigger (<50ms, no LLM, no network), smart filter: the session model decides whether to surface anything.
- It compounds. One brief per domain in a real knowledge base. Re-scouts are delta passes, never duplicates. The radar gets quieter as your map gets larger, and
/scout debrieffolds what the build taught you back into the brief - including which watch-list items never fired, because miscalibration is data too.
Source discipline over verification ceremony. Every claim in a brief carries a tag: [primary] (a source was fetched and supports it), [secondary], or [model-inference] (the agent is asserting from training). Agreement between agents never earns [primary] - shared priors are the mechanism behind confident consensus error, not evidence against it. A vocabulary table with three honest [model-inference] rows is worth more than one where all fifteen imply authority.
| Piece | Where | Role |
|---|---|---|
/scout skill (SKILL.md + METHOD.md) |
~/.claude/skills/scout/ |
The brain - scoping, blind-lens sweeps, critic, brief compilation, routing |
| Deep-mode workflow | ~/.claude/workflows/scout-deep.js |
Committed orchestration for /scout deep - reproducible and resumable, not re-derived per run |
| Radar hook | ~/.claude/hooks/scout_radar.py + registered in settings.json |
Always-on regex tripwire on every prompt (<50ms, 1/session, 3/day caps) |
| Grading rubric | ~/.claude/rubrics/scout-brief.md |
Briefs are graded by a fresh-context verifier - never self-certified |
| Verifier agent | ~/.claude/agents/verifier.md |
Independent rubric grader (installed only if you don't already have one) |
| Knowledge base | ~/kb/scout/ (raw/, wiki/, outputs/ + compile protocol) |
One brief per domain; re-scouts are delta passes, never duplicates |
| State | ~/.claude/state/scout/ |
Ledger of scouted domains + radar rate-limit state (created empty), and skill backups under backups/ |
The installer is idempotent. It backs up any existing skill to ~/.claude/state/scout/backups/scout-<timestamp>/ - deliberately outside ~/.claude/skills/, because anything under skills/ is registered as a skill, so a backup copy there would show up as a second /scout with an identical trigger description and compete with the real one. It never overwrites knowledge-base content or your existing verifier agent.
A summary of the flow, not the full protocol - SKILL.md's numbered steps are the contract (they add a task fingerprint before the draft map and a surface-and-route step before verification).
- Radar - a deliberately dumb regex hook watches every prompt. Strong path: explicit uncertainty phrasing ("I don't even know what's possible"). Weak path: an endeavor verb and a novelty marker in a substantial prompt, because "build" alone matches nearly everything.
- Premise check - before spawning anything: what assumption must be true for this task to matter, what happens if you do nothing, what simpler thing might already solve 80%. Verdict STRONG / QUESTIONABLE / WEAK. The cheapest scout is the one that proves the territory isn't worth mapping.
- Draft map - a 5-8 item guess at what this touches, guesses tagged as guesses, which you correct before the sweep spends tokens. Every "no, actually…" sharpens the lens prompts for free.
- Sweep - parallel agents blind to each other, one per lens: Lexicon & Map, Toolsmith, Elder (tribal knowledge, mined from issues, PRs, changelogs, and postmortems rather than blog posts), plus Territory (a blindspot pass over your repo when a codebase is in play). Every item comes back source-tagged; the map records typed relationships between terms, not just definitions; and each lens reports its surprises - contradictions, conflicting definitions, everywhere-but-unsourced claims - as first-class output.
- Critic - one fresh agent that starts from the reported surprises (agents reliably notice contradicting evidence and then fail to act on it), then hunts what's missing: a modality never run, a relationship the map asserts but nothing evidences, a load-bearing source cited but never followed one hop outward, a claim left
[model-inference]. Its findings spawn a targeted round. A scout that can't ask what it missed is subject to the failure it exists to prevent. - Interview - the sweep only covers what the web can know. Scout then asks you 3-5 questions, architecture-altering first, each with its evidence anchor, what changes depending on the answer, and a recommended default so you can confirm rather than compose. An unknown counts as settled only on your articulation - scout writing a plausible answer into the brief resolves nothing, and gets recorded as an assumption.
- Brief - sixteen sections filed to
~/kb/scout/wiki/: premise check, vocabulary (≥15 tagged terms), territory map, canonical resources, tribal knowledge, local territory (file:line), an options landscape with S-XL effort tags and a stated recommendation (flip condition + biggest risk, never a bare "it depends"), the questions you didn't know to ask, a four-quadrant gap diff, a coverage audit naming what this brief still doesn't cover, a watch-list of unknowns likely to surface mid-build, and a ready-to-paste prompt scaffold. - Verify - a fresh-context verifier grades the brief against the rubric. It fetch-checks cited sources (every curated index and community, since those are what you're least able to check yourself), fails untagged claims, and fails a brief with no coverage audit.
- Compound - the ledger grows; the radar reads it and quiets down. Each brief commits to a volatility verdict (fast / steady / stable) that sets its own re-scout window instead of a flat 30 days. After you build,
/scout debrief <slug>folds what the territory taught you back into the map - including whether the volatility call held.
Modes: /scout quick <topic> (inline, nothing filed) · /scout <topic> (standard) · /scout deep <topic> (six lenses across five agents + critic loop-until-dry via the committed workflow) · /scout debrief <slug> (post-build delta).
Scout's lift over a single good search is unmeasured. eval/README.md defines the harness - 5 scenarios x 2 models x 2 arms, blind cross-model grading, null results reported - and states plainly what is and isn't known today. Correctness properties (the verifier fails briefs on countable criteria, the radar fires on intended phrasing, the install is idempotent) are verified; quality lift is not. Treating that as a visible gap rather than an implicit claim is the point.
The four-quadrant unknowns frame (known/unknown × known/unknown), the local blindspot pass, the user interview, the prompt scaffold with its specificity-balance rule, and the debrief loop are adopted from Thariq Shihipar's "A Field Guide to Claude Fable 5: Finding Your Unknowns" (Anthropic, July 2026). His thesis - the map is not the territory, and output quality is bounded by how well you discover your own unknowns before prompting - is exactly the job scout automates. Scout is a superset rather than a port: the blind-lens sweep, the rubric-graded verification, the tripwire, and the compounding KB are orchestration the field guide doesn't attempt.
The cheap-model sweep lanes ("spend the expensive model on judgment, cheap models on volume") and the five-part spec shape for delegated-build scaffolds are adapted from DannyMac180/fable-advisor's architect pattern.
The premise check (assumption / inaction cost / 80% alternative / hard verdict), the no-"it-depends" recommendation rule (stated preference + flip condition + biggest risk), scope-and-risk effort tags, and the one-batched-message interview discipline are adapted from the brainstorm skill in indigoai-us/hq-core - anti-sycophancy as structure, not tone.
Three later borrowings, credited where they landed:
- Settle-on-articulation (an unknown is resolved only when the user articulates it) and hypotheses-not-diagnosis (open with a correctable draft map) are from junjunjunbong/into-the-unknown.
- The question quality bar - every interview question carries a citation, a why-it-matters, and a recommended default; low-risk unknowns become labeled assumptions instead of questions - is from nicobailon/grill-for-unknowns, whose framing is worth quoting: "'Relentless' is a personality, not a quality bar."
- Source-bound tagging and the rule that
[verified]must mean a primary source was fetched come from anthropics/claude-code#66375, which documented/deep-researchshipping confidently-wrong[verified]claims whose errors clustered in exactly the ones drawn from secondary aggregators and model knowledge. Its finding - accuracy tracked sourcing discipline, not the voting machinery - is why scout's rubric fetch-checks sources as a required criterion rather than an advisory one.
The evaluation design follows oso95/finding-unknowns, the only project in this space that measured itself and published its null results.
Four borrowings from the 2026 deep-research literature, folded into the method rather than added as machinery:
- The surprise queue follows the April 2026 finding on environmental curiosity: agents frequently encounter highly useful or contradicting evidence and then fail to exploit it. Scout's answer is structural - surprises are a required lens output, the critic's mandatory starting point, and the brief's contradiction log.
- The critic-as-navigator framing (start from a shared evidence map, hunt unsupported relationships, dispatch targeted searches rather than redundant ones) follows Argus (May 2026), whose searchers-plus-Navigator architecture carried the strongest quantitative evidence among recent multi-agent research designs.
- Relationships, not just definitions follows DualGraph: an outline encourages filling predetermined sections, while a knowledge graph reveals the gaps - two concepts everyone treats as related with no connecting evidence, one term with conflicting definitions. Scout's map section is an ontology (typed links) for the same reason.
- One-hop source expansion in the critic (what does the canonical index itself reference; who critiques or extends it) is citation snowballing, per the May 2026 literature-search study where following citation networks raised recall from under 20% to over 80%.
Genome - scout maps territory ahead; genome dissects ideas behind (12-layer idea autopsies → generative principles).
rm -rf ~/.claude/skills/scout ~/.claude/hooks/scout_radar.py \
~/.claude/rubrics/scout-brief.md ~/.claude/workflows/scout-deep.js \
~/.claude/state/scout
# then remove the scout_radar.py entry from hooks.UserPromptSubmit in ~/.claude/settings.json
# ~/.claude/agents/verifier.md: remove it only if scout installed it - the installer never
# touches a pre-existing verifier, and other tooling may use yours
# ~/.claude/state/genome/ is shared with the genome sibling - remove only if genome is gone too
# your briefs in ~/kb/scout/ are yours - delete only if you want toMIT