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:

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:

// 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:

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:

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:

// 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:

🐕 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

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:

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:

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

# 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:

### 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:

- 
🐕 SCENT — "Starting with 'payment' keyword, searching for components, services, API routes"

- 
🐕 TRACK — "Found PaymentForm component → calls paymentService → uses Stripe SDK → webhooks in +server.ts"

- 
🐕 HUNT — "Deep dive: error handling, idempotency keys, webhook signature verification, retry logic"

- 
🐕 REPORT — "Complete flow map, 7 files involved, 2 inconsistent patterns found, 1 security recommendation"

- 
🐕 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. 🐕