scout

name

scout

description

Map a domain's unknown unknowns before committing to an approach — terms of art, taxonomies, canonical tools and libraries, named methods, tribal knowledge, and the questions you didn't know to ask. Produces a verifier-graded domain brief filed to ~/kb/scout/ plus routed gap candidates. Use when starting work in an unfamiliar domain or new project, before /ce-plan, /ce-brainstorm, or design work, when the user says "scout", "what am I missing", "what don't I know", "what's possible", "map the territory", or "unknown unknowns", or when a <scout-radar> context note fires.

Scout — map the territory before you walk it

Goal: convert unknown unknowns into known unknowns. The deliverable is a domain brief — vocabulary, territory map, canonical resources, tribal knowledge, and routed next actions — NOT an answer to the task. Scout names things; other skills resolve them.

Modes

Invocation	Depth	Use
/scout quick <topic>	inline, no subagents	mid-task micro-scout of one concept cluster; ~10-line vocabulary + resources reply, no brief filed
/scout <topic or task>	3–4 parallel sweep agents + critic + verifier	default — new domain, new project, radar fire
/scout deep <topic>	committed Workflow: six lenses across five agents + critic loop-until-dry	high-stakes coverage; user accepts the token cost
/scout debrief <slug>	inline, no sweep	post-implementation: fold deviations and implementation notes back into an existing brief as a dated delta

Protocol (standard mode)

0. Scope + ledger. Name the domain and the task it serves. Check ~/.claude/state/scout/domains.json and grep ~/kb/ (vault-first rule). Scouted within the brief's recheck window (the ledger's recheck_days, from its volatility verdict; default 30d) → surface the existing brief, run a delta pass only. Well-covered by an existing KB → say so and stop. Then challenge the premise before spawning anything: what assumption must be true for this task to matter, what happens if we do nothing, and what simpler thing might already solve 80%. Verdict: STRONG / QUESTIONABLE / WEAK — a WEAK verdict goes to the user before any sweep agents spawn; the cheapest scout is the one that proves the territory isn't worth mapping.
1. Fingerprint. Decompose the task into the 2–5 fields it actually touches (e.g. "beautiful landing page" → motion design, typography, layout systems, perceived performance). If the task touches an existing codebase or project, the local repo IS part of the territory — flag it for the Territory lens.
2. Draft map — hypotheses, not a diagnosis. Before spending sweep tokens, show the user a 5–8 item draft: the fields you think this touches, what you're guessing (tagged as guesses), and what you think they already know. They correct it. Every "no, actually…" sharpens the lens prompts for free and is the mechanism working, not a detour. Interactive session only — autonomous runs skip straight to the sweep and file the draft in the brief instead.
3. Sweep — blind angles. Spawn parallel research agents, one per lens, prompts from METHOD.md: Lexicon & Map (terms of art + taxonomy), Toolsmith (canonical stack, curated indexes, communities), Elder (tribal knowledge: practitioner heuristics, traps, amateur-vs-pro markers), plus Territory (local blindspot pass over the repo — only when a codebase is in play). Each agent is blind to the others. Every claim comes back with a source tag ([primary] / [secondary] / [model-inference]), and every lens reports its surprises — contradictions, conflicting definitions, everywhere-but- unsourced claims — as first-class output, never smoothed into the findings. See METHOD.md.
4. Gap diff — four quadrants. Compare sweep output against existing kb/memory/work-vault coverage (cite paths checked). Separate already-known from net-new, then classify each net-new gap: known unknown (a question you knew to ask), unknown unknown (net-new from the sweep), or unknown known (tacit context only the user holds — feed these to step 6's interview). Rank by leverage on the current task.
5. Completeness critic. One agent, fresh angle, no access to the sweep's reasoning. It starts from the lenses' reported surprises — noticing contradicting evidence and then not acting on it is the documented agent failure mode — then hunts what's missing: a modality not run, a community unchecked, a claim still [model-inference], a relationship the map asserts but nothing evidences, a load-bearing source cited but never followed one hop outward. Its findings spawn ONE targeted round in standard mode (deep mode loops until dry). Record the verdict, the contradiction log, and what stayed open in the brief's Coverage audit. A scout that can't ask what it missed is subject to the failure it exists to prevent.
6. Interview — unknown knowns. Draft 3–5 prioritized questions for the user, ordered by how much the answer would change the approach (architecture-altering first). None should be answerable by web search — that's the sweep's job. Every question carries its evidence anchor, a one-line why-it-matters, and a recommended default (question quality bar in METHOD.md). Batch everything into ONE message; skip any question the sweep, the repo, or the conversation already answers; zero questions is a valid outcome. Interactive session → ask via AskUserQuestion; autonomous → file under "Questions for you" in the brief. Half the territory is context only the user holds; no sweep agent can find it.
7. Brief. Compile to the template in METHOD.md → file per ~/kb/scout/.claude/CLAUDE.md (raw deposit, wiki compile, _index bump, log entry). Cross-link [[wikilinks]] into topic KBs. Recheck the premise against what the sweep found: step 0's verdict was made blind, and unknowns discovered mid-flight can mean the task should be solved a different way altogether. If the evidence flipped or reframed the premise, the brief leads with that — a premise overturned by discovery is scout's best possible outcome, not a detour.
8. Surface + route. In conversation: top 5 gaps, one line each, with a routed next action (table below); close with the brief's prompt scaffold — a ready-to-paste context block for the follow-on prompt or plan. Update the ledger; optionally append top gaps to a Meridian-style inbox if you run one (formats in METHOD.md).
9. Verify. Spawn the verifier agent: rubric ~/.claude/rubrics/scout-brief.md, artifact = the brief. Fix required failures once; never self-certify.

Routing resolved gaps

Route to the capability, not a slug you may not have. Preferred tool first, then a fallback that works on a bare Claude Code install.

Gap type	Preferred	Fallback
Need to understand a concept	a teach / learn skill	ask directly with the brief's vocabulary section as context
Stress-test understanding	grill-with-docs / grilling	"quiz me on this until I can explain it without notes"
What practitioners use/discuss right now	/signalsweep <topic> or /last30days <topic>	WebSearch scoped to the communities the Toolsmith lens found
Deep multi-source dive on one question	a deep-research skill	built-in /deep-research workflow
Library/API specifics	Context7 (resolve-library-id → get-library-docs)	WebFetch the canonical docs URL from the brief
Apply to design work	a frontend-design skill	the brief's prompt scaffold + source-code references
Plan the build	compound-engineering:ce-plan	/scout's prompt scaffold straight into plan mode
Visualize the territory	an excalidraw/diagram skill	a mermaid diagram from the brief's map section
Dissect a specific novel idea (not a domain)	/genome <idea> — sibling skill	—
After the build: fold what the walk taught you back into the map	/scout debrief <slug>	—

Rules

• Vault first, always. Never re-scout what ~/kb/ already covers — delta passes only, cite the hits.
• Radar fires are tripwires, not verdicts. On a <scout-radar> note: check ledger + kb; if covered or routine, stay completely silent about scout. If genuinely new, offer /scout "<domain>" in ONE line.
• Brief ≠ tutorial. Optimize for naming things precisely and linking out; depth is other skills' job.
• Sources or it didn't happen. Every resource gets a URL; every claim a source tag; agents report their angle. [primary] requires a fetched source — agreement between agents is not evidence, because independent agents sharing a prior produce confident consensus error.
• Chase surprises first. Evidence that contradicts the emerging map outranks evidence that confirms it. Agents reliably notice surprising evidence and then fail to use it — so surprises are a required lens output, the critic's starting point, and the coverage audit's contradiction log, not color commentary.
• Settled means the user said it. An unknown counts as resolved only on the user's own articulation: a decision they made, a criterion they voiced, an explanation they gave back. Scout writing the answer into the brief only moves the unknown from their head into a file — record that as an assumption, not a resolution.
• Never self-certify — verifier + rubric on every filed brief (quick and debrief modes exempt from a fresh verify: quick files nothing; debrief appends to an already-verified brief).
• Propose, don't promote. The brief and conversation surface gaps; the user decides what gets pursued.
• Better prompts, not just briefs. The end product is a sharper follow-on prompt. The scaffold states known knowns, flags open known unknowns, and attaches references — source code beats screenshots, because downstream agents read code, not pixels.
• Specificity balance. Enough context to avoid generic output; not so much prescription that a flawed approach gets locked in. State the starting point and experience level; leave the how loosest where certainty is lowest.

Sweep-agent prompts, question quality bar, brief template, ledger/inbox formats, deep-mode workflow: METHOD.md