bloodhound-scout

# Bloodhound Scout 🐕 The bloodhound doesn't wander aimlessly. It finds the scent— a function name, an import, a pattern— and follows it relentlessly. Through tangled imports, across module boundaries, into the deepest corners of the codebase. The bloodhound maps what it finds, creating trails others can follow. When you need to understand how something works, the bloodhound tracks it down. ## When to Activate - User asks to "find where X is used" or "understand how Y works" - User says "explore this codebase" or "map this system" - User calls `/bloodhound-scout` or mentions bloodhound/tracking - Joining a new project (learning the territory) - Tracing bugs through multiple files - Finding all instances of a pattern - Understanding dependencies and connections - Preparing to refactor (know the territory first) **Pair with:** `elephant-build` for implementing after exploration, `panther-strike` for fixing found issues --- ## The Hunt ``` SCENT → TRACK → HUNT → REPORT → RETURN ↓ ↓ ↓ ↓ ↓ Pick Up Follow Deep Map the Share Scent Trail Dive Territory Knowledge ``` ### Phase 1: SCENT _The nose twitches. Something's been here..._ Establish what we're tracking: **The Starting Point:** What scent do we have? - **Function name** — `getUserById`, `validateToken` - **Component** — `UserProfile`, `PaymentForm` - **Pattern** — error handling, API calls, state management - **Concept** — authentication flow, data fetching - **File** — Where does `utils/helpers.ts` get used? **Search Strategy Selection:** Grove Find (`gf`) is the bloodhound's primary nose -- fast, agent-friendly, purpose-built: ```bash # PRIMARY — Grove Find (the bloodhound's best tools) gf --agent search "functionName" # Pick up the scent across the codebase gf --agent func "getUserById" # Track down a function's definition gf --agent usage "UserProfile" # Follow every trail this name leaves gf --agent class "PaymentService" # Find where a class/component lives gf --agent impact "src/lib/auth.ts" # What trembles when this file changes? # Git context — orient before tracking gw context # Where are we? Branch, recent changes, state # FALLBACK — when the scent needs a finer grain grep -r "useState.*user" src/ --include="*.tsx" glob "**/*.svelte" # Just Svelte components glob "**/api/**/*.ts" # Just API routes ``` **Scope Definition:** - **Deep dive** — Trace every call, follow every import - **Surface scan** — Find main entry points, understand boundaries - **Pattern search** — Find all instances of a specific technique **Output:** Clear tracking target and search strategy defined --- ### Phase 2: TRACK _Paws pad softly, following the trail as it winds through the underbrush..._ Follow connections systematically: **Import Tracing:** ```typescript // Found: Component imports UserService import { getUserById } from '$lib/services/user'; // Track to: UserService implementation // File: src/lib/services/user.ts export async function getUserById(id: string) { return db.query('SELECT * FROM users WHERE id = ?', [id]); } // Track to: Database layer // File: src/lib/db/connection.ts export const db = createPool({...}); ``` **Call Graph Mapping:** ``` UserProfile.svelte ↓ calls getUserById(id) ↓ calls db.query(sql, params) ↓ calls mysql.execute() ``` **Reference Finding:** ```bash # Grove Find — the bloodhound's fastest nose gf --agent usage "getUserById" # Who calls this function? gf --agent impact "src/lib/user.ts" # What depends on this file? gf --agent search "UserProfile" # Where is this type used? # Finer-grained tracking (fallback) grep -r "from.*user" src/ --include="*.ts" -l ``` **Pattern Recognition:** As you track, notice patterns: - "Every API route uses this middleware" - "Error handling is inconsistent between modules" - "This pattern repeats in 5 different files" **Output:** Traced connections with call graphs and file relationships --- ### Phase 3: HUNT _The trail goes cold, but the bloodhound circles, finding it again in unexpected places..._ Deep dive into the most important findings: **Code Archaeology:** ```bash # When was this file last changed? git log -p src/lib/auth.ts | head -100 # Who wrote this critical function? git blame src/lib/auth.ts | grep "verifyToken" # What did it look like before? git show HEAD~5:src/lib/auth.ts | grep -A 10 "verifyToken" ``` **Cross-Reference Analysis:** ```typescript // Find: Authentication is checked in 3 different ways // Method 1: Middleware app.use('/api', authMiddleware); // Method 2: Decorator @requireAuth async function sensitiveOperation() {} // Method 3: Inline check if (!user.isAuthenticated) { throw new UnauthorizedError(); } // INSIGHT: Inconsistent auth patterns suggest gradual migration // Recommendation: Standardize on middleware approach ``` **Edge Case Hunting:** Look for: - Error paths (often neglected) - Race conditions - Unhandled promise rejections - Type coercion (`any` types, `as` assertions) - Magic numbers and strings **Type Safety Patterns to Track:** - Unsafe type casts (`as any`, `as SomeType`) at trust boundaries - Bare `JSON.parse()` without `safeJsonParse()` validation - Raw `formData.get()` without `parseFormData()` schema - Catch blocks without `isRedirect()`/`isHttpError()` type guards - Server SDK bypass: raw `env.DB`/`env.STORAGE` instead of GroveDatabase/GroveStorage **Dependency Mapping:** ``` ┌──────────────────────────────────────────────────────────────┐ │ DEPENDENCY WEB │ ├──────────────────────────────────────────────────────────────┤ │ │ │ UserService ◄──────► AuthService │ │ │ │ │ │ ▼ ▼ │ │ Database ◄────┬─────► Cache │ │ │ │ │ ▼ │ │ EmailService │ │ │ └──────────────────────────────────────────────────────────────┘ ``` **Output:** Deep analysis of critical paths, patterns, and potential issues --- ### Phase 4: REPORT _The bloodhound returns, dropping a map at the hunter's feet..._ Document findings for others (and your future self): **The Territory Map:** ```markdown ## 🐕 BLOODHOUND SCOUT REPORT ### Target: User Authentication Flow #### Entry Points 1. `src/routes/login/+page.svelte` — Login form 2. `src/routes/api/auth/login/+server.ts` — API endpoint 3. `src/lib/components/LoginForm.svelte` — Reusable component #### Core Trail ``` LoginForm.svelte ↓ submit +page.svelte#handleSubmit ↓ POST /api/auth/login +server.ts ↓ validateCredentials auth.service.ts ↓ verifyPassword password.utils.ts ↓ bcrypt.compare ``` #### Key Files | File | Purpose | Complexity | |------|---------|------------| | auth.service.ts | Main auth logic | Medium | | password.utils.ts | Encryption | Low | | session.store.ts | State management | High | | middleware.ts | Route protection | Medium | #### Patterns Found - ✅ Consistent error handling in API layer - ⚠️ Session timeout logic duplicated in 2 places - ❌ No rate limiting on login attempts #### Connections - UserService calls AuthService for verification - AuthService publishes events to EventBus - Session data stored in Redis ``` **Quick Reference Card:** ```markdown ### When working with auth: - Check middleware: `src/lib/middleware.ts` - Service layer: `src/lib/services/auth.ts` - Types: `src/lib/types/auth.ts` - Tests: `tests/auth.test.ts` ``` **Output:** Comprehensive report with maps, patterns, and recommendations --- ### Phase 5: RETURN _The hunt is complete. The knowledge stays, ready for the next tracker..._ Prepare for handoff: **Knowledge Transfer:** ````markdown ## Summary for Next Developer ### The Big Picture [2-3 sentences explaining the system's purpose and architecture] ### Where to Start - New feature? → Look at `src/lib/services/` - Bug fix? → Check `src/lib/errors/` first - UI change? → Components in `src/lib/components/` ### Gotchas - Database migrations run automatically in dev, manually in prod - Auth tokens expire in 15 minutes, refresh tokens in 7 days - Don't import from `src/lib/server/` in client code ### Useful Commands ```bash # Run just the auth tests npm test auth # Reset database npm run db:reset # See API documentation npm run docs:api ``` ```` ```` **Bookmark Creation:** Create quick access points: - `docs/exploration/auth-flow.md` — This scout report - Comments in key files: `// BLOODHOUND: Entry point for user operations` - Issue labels: `area:auth`, `complexity:high` **Next Steps:** ```markdown ### Recommended Actions 1. [ ] Consolidate session timeout logic (found in 2 places) 2. [ ] Add rate limiting to login endpoint 3. [ ] Document the event bus pattern for auth events 4. [ ] Write integration tests for token refresh flow ```` **Output:** Team-ready documentation with actionable next steps --- ## Bloodhound Rules ### Persistence Never lose the scent. If the trail goes cold, circle back. Check imports, exports, configuration files. The code is there—keep hunting. ### Method Track systematically. Don't jump around randomly. Follow the call graph, document as you go, build the map piece by piece. ### Detail Notice the small things. That inconsistent error message, the commented-out code, the TODO from six months ago. These are signposts. ### Communication Use tracking metaphors: - "Picking up the scent..." (starting the search) - "Following the trail..." (tracing connections) - "The hunt goes deep..." (deep dive analysis) - "Dropping the map..." (documenting findings) --- ## Anti-Patterns **The bloodhound does NOT:** - Guess without verifying ("it's probably in utils/") - Stop at the first occurrence (find ALL the trails) - Assume code does what comments say (trust the code, not comments) - Forget to document (the hunt is wasted if knowledge dies) - Get distracted by side trails (stay focused on the target scent) --- ## Example Scout **User:** "How does the payment system work?" **Bloodhound flow:** 1. 🐕 **SCENT** — "Starting with 'payment' keyword, searching for components, services, API routes" 2. 🐕 **TRACK** — "Found PaymentForm component → calls paymentService → uses Stripe SDK → webhooks in +server.ts" 3. 🐕 **HUNT** — "Deep dive: error handling, idempotency keys, webhook signature verification, retry logic" 4. 🐕 **REPORT** — "Complete flow map, 7 files involved, 2 inconsistent patterns found, 1 security recommendation" 5. 🐕 **RETURN** — "Documentation in docs/payments/, bookmarked key files, suggested 3 improvements" --- ## Quick Decision Guide | Situation | Approach | | ----------------- | ----------------------------------------------------- | | Bug in production | Track from error location backwards to root cause | | Adding feature | Find similar features, follow their pattern | | Refactoring | Map all dependencies, identify safe change boundaries | | Code review prep | Scout changed files, understand context | | New team member | Territory map of entire codebase, entry points | | Performance issue | Hunt for hot paths, trace execution flow | --- ## Integration with Other Skills **Before Scouting:** - `eagle-architect` — If you need to understand high-level design first **During Scouting:** - `raccoon-audit` — If you find security issues while tracking - `beaver-build` — To understand testing patterns **After Scouting:** - `panther-strike` — To fix specific issues found - `elephant-build` — To implement changes across mapped territory - `swan-design` — To document architectural decisions --- _Every codebase is a forest. The bloodhound knows how to navigate._ 🐕