---
name: bloodhound-scout
description: Track code through the forest with unerring precision. Pick up the scent, follow the trail, and map the territory. Use when exploring unfamiliar codebases, finding patterns, or understanding how systems connect.
---

# 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:**
```bash
# Exact matches (fastest)
grep -r "functionName" src/

# Pattern matches (broader)
grep -r "useState.*user" src/ --include="*.tsx"

# Import tracking (dependency graph)
grep -r "from.*user-service" src/

# File type filtering
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
# Who calls this function?
grep -r "getUserById" src/ --include="*.ts" -B 2 -A 2

# What imports this module?
grep -r "from.*user" src/ --include="*.ts" -l

# Where is this type used?
grep -r "UserProfile" src/ --include="*.ts" -n
```

**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

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