Scout — Smart Codebase Explorer
Explore the codebase for files, patterns, architecture insights, and implementations. Auto-detects platform and intelligently routes between RAG (semantic search) and Grep (exact matches) with graceful fallback.
Flags
| Flag |
Behavior |
| (none) |
Auto mode — smart routing: RAG for semantic queries, Grep for exact matches |
--fast |
Grep only — no RAG, no external service. Fast, offline-friendly, exact matches |
--deep |
Exhaustive — RAG + Grep merged, all results returned and ranked |
Query
$ARGUMENTS
Step 1: Parse Flags & Query
- Strip
--fast or --deep from $ARGUMENTS before processing
- Default mode if no flag: auto
Step 2: Classify Query Intent
- File location — "where is X", "find the Y", "which file has Z"
- Pattern/Implementation — "how is X implemented", "show me the code for Y", "trace X"
- Architecture/Structure — "what does X do", "how does the Y work", "architecture of Z"
- Dependencies/Relationships — "what calls X", "where is X used", "dependencies of Y"
Step 3: Detect Platform(s)
- Explicit prefix —
web:, ios:, android:, backend: at query start
- Query keywords — "React", "SwiftUI", "Compose", "JAX-RS" → platform inference
- Default — if ambiguous, search all platforms (deduplicate by relevance)
Step 4: Search Routing
--fast mode (Grep only)
| Query Type |
Tool |
Strategy |
| Filename |
Glob |
**/{filename}* |
| String/symbol |
Grep |
Literal string match |
| Regex pattern |
Grep |
Full regex support |
| Platform-specific |
Grep + Glob |
Filter by extension (.tsx, .swift, .kt, .java) |
auto mode (Smart routing)
| Intent |
Platform |
Strategy |
| Exact file name |
any |
Glob/Grep filename |
| Implementation / pattern |
web |
web-rag → fallback Grep |
| Implementation / pattern |
ios |
ios-rag → fallback Grep |
| Implementation / pattern |
android/backend |
Grep only |
| Architecture / design |
any |
docs/ first → Grep → RAG |
| Dependencies |
any |
Grep for imports |
--deep mode (RAG + Grep merged)
Run both RAG semantic search AND Grep, merge and deduplicate results ranked by relevance.
Step 5: RAG Integration (auto and --deep modes)
- Lazy health check — attempt query, catch errors gracefully
- Query construction — "Find [component/token/pattern] matching [intent]"
- Filter extraction — extract filters from query. Use canonical component names:
web-rag/references/component-mappings.md or ios-rag/references/component-mappings.md
- Result limit — top 10–15 (auto), all available (--deep)
- Fallback — if RAG fails or returns empty, use Grep silently
Offline fallback: RAG unavailable → use Grep. Do NOT report RAG failure.
Step 6: Result Categorization & Synthesis
Group by category:
| Category |
Signals |
| Components |
.tsx/.jsx (web), .swift (iOS), .kt (Android), .java (backend) |
| Logic/Utils |
hooks, helpers, services, utils, managers |
| Tokens/Config |
design tokens, theme, config, constants |
| Tests |
.test.ts, .test.swift, Test.kt, *Test.java |
| Docs |
.md, .mdx files |
Per result: file path (relative) · one-line summary · platform tag · relevance badge
Step 7: Rank & Report
Rank by: exact filename > same platform > RAG score > match frequency
- auto/--fast: top 10 results. If >15, hint: "Run
/scout --deep [query] for all results"
- --deep: all results in sections (Semantic Matches / Exact Matches / By Category)
Examples
/scout auth flow → auto search all platforms/scout web: Button component → web-rag semantic for Button/scout ios: navigation → ios-rag semantic for navigation/scout --fast useAuth → grep-only, no RAG/scout --fast web: route.ts → grep for route.ts in web/scout --deep Button → all Button-related code, RAG + grep merged/scout --deep web: authentication → exhaustive auth search in web
1---2name: scout-63description: (ePost) Use when you need to "find files", "search the codebase", "locate a pattern", "explore the repo", or "what exists for X" — searches across platforms using RAG and grep4---5
6# Scout — Smart Codebase Explorer
7
8Explore the codebase for files, patterns, architecture insights, and implementations. Auto-detects platform and intelligently routes between RAG (semantic search) and Grep (exact matches) with graceful fallback.
9
10## Flags
11
12| Flag | Behavior |
13|------|----------|
14| *(none)* | **Auto mode** — smart routing: RAG for semantic queries, Grep for exact matches |
15| `--fast` | **Grep only** — no RAG, no external service. Fast, offline-friendly, exact matches |
16| `--deep` | **Exhaustive** — RAG + Grep merged, all results returned and ranked |
17
18## Query
19
20<query>$ARGUMENTS</query>
21
22## Step 1: Parse Flags & Query
23
24- Strip `--fast` or `--deep` from `$ARGUMENTS` before processing
25- Default mode if no flag: **auto**
26
27## Step 2: Classify Query Intent
28
29- **File location** — "where is X", "find the Y", "which file has Z"
30- **Pattern/Implementation** — "how is X implemented", "show me the code for Y", "trace X"
31- **Architecture/Structure** — "what does X do", "how does the Y work", "architecture of Z"
32- **Dependencies/Relationships** — "what calls X", "where is X used", "dependencies of Y"
33
34## Step 3: Detect Platform(s)
35
361. **Explicit prefix** — `web:`, `ios:`, `android:`, `backend:` at query start
372. **Query keywords** — "React", "SwiftUI", "Compose", "JAX-RS" → platform inference
383. **Default** — if ambiguous, search all platforms (deduplicate by relevance)
39
40## Step 4: Search Routing
41
42### --fast mode (Grep only)
43
44| Query Type | Tool | Strategy |
45|------------|------|----------|
46| Filename | Glob | `**/{filename}*` |
47| String/symbol | Grep | Literal string match |
48| Regex pattern | Grep | Full regex support |
49| Platform-specific | Grep + Glob | Filter by extension (.tsx, .swift, .kt, .java) |
50
51### auto mode (Smart routing)
52
53| Intent | Platform | Strategy |
54|--------|----------|----------|
55| Exact file name | any | Glob/Grep filename |
56| Implementation / pattern | **web** | web-rag → fallback Grep |
57| Implementation / pattern | **ios** | ios-rag → fallback Grep |
58| Implementation / pattern | **android/backend** | Grep only |
59| Architecture / design | any | docs/ first → Grep → RAG |
60| Dependencies | any | Grep for imports |
61
62### --deep mode (RAG + Grep merged)
63
64Run both RAG semantic search AND Grep, merge and deduplicate results ranked by relevance.
65
66## Step 5: RAG Integration (auto and --deep modes)
67
681. **Lazy health check** — attempt query, catch errors gracefully
692. **Query construction** — "Find [component/token/pattern] matching [intent]"
703. **Filter extraction** — extract filters from query. Use canonical component names: `web-rag/references/component-mappings.md` or `ios-rag/references/component-mappings.md`
714. **Result limit** — top 10–15 (auto), all available (--deep)
725. **Fallback** — if RAG fails or returns empty, use Grep silently
73
74**Offline fallback**: RAG unavailable → use Grep. Do NOT report RAG failure.
75
76## Step 6: Result Categorization & Synthesis
77
78Group by category:
79
80| Category | Signals |
81|----------|---------|
82| **Components** | .tsx/.jsx (web), .swift (iOS), .kt (Android), .java (backend) |
83| **Logic/Utils** | hooks, helpers, services, utils, managers |
84| **Tokens/Config** | design tokens, theme, config, constants |
85| **Tests** | .test.ts, .test.swift, Test.kt, *Test.java |
86| **Docs** | .md, .mdx files |
87
88Per result: file path (relative) · one-line summary · platform tag · relevance badge
89
90## Step 7: Rank & Report
91
92Rank by: exact filename > same platform > RAG score > match frequency
93
94- **auto/--fast**: top 10 results. If >15, hint: "Run `/scout --deep [query]` for all results"
95- **--deep**: all results in sections (Semantic Matches / Exact Matches / By Category)
96
97## Examples
98
99- `/scout auth flow` → auto search all platforms
100- `/scout web: Button component` → web-rag semantic for Button
101- `/scout ios: navigation` → ios-rag semantic for navigation
102- `/scout --fast useAuth` → grep-only, no RAG
103- `/scout --fast web: route.ts` → grep for route.ts in web
104- `/scout --deep Button` → all Button-related code, RAG + grep merged
105- `/scout --deep web: authentication` → exhaustive auth search in web
majiayu000