Bug Detective Workflow

Purpose

Conduct systematic, methodical bug investigations using detective-style debugging. This workflow combines Sherpa's bug hunt phases, Julie's execution tracing, and Goldfish's investigation logging to find and fix bugs confidently.

When to Activate

Use when the user:

• Reports bugs: "this is broken", "getting an error", "not working"
• Debugs issues: "debug this", "find the bug", "why is this failing"
• Investigates problems: "investigate this error", "track down this issue"
• Unexpected behavior: "this should work but doesn't", "weird behavior"

The Detective Trinity

🕵️ Sherpa - Investigation Guidance

• 4-phase bug hunt workflow
• Detective metaphors and encouragement
• Systematic process
• Progress tracking

🔍 Julie - Code Investigation Tools

• Semantic error search
• Execution path tracing
• Cross-language navigation
• Reference finding

📝 Goldfish - Investigation Log

• Checkpoint discoveries
• Document hypotheses
• Track investigation steps
• Preserve solution

Bug Detective Orchestration

Session Start: Check Previous Investigations

1. Goldfish recall({ search: "[error/bug description]" })
   → See if similar bug investigated before
2. Learn from previous investigations
3. If same bug → Resume investigation
4. If new → Start fresh investigation

Phase 1: 🔍 Reproduce & Isolate

Sherpa Activation:

approach({ workflow: "bug-hunt" })
guide() → "Phase 1: Reproduce & Isolate - Find the crime scene!"

Error Discovery: User reports: "Getting 'Invalid token' error"

Julie Investigation:

fast_search({ query: "Invalid token", mode: "lines" })
→ Find all error message locations

fast_goto on error location
→ Jump to where error is thrown

trace_call_path({ symbol: "validateToken", direction: "upstream" })
→ See what calls this (who triggers the error?)

Reproduce Reliably:

• Identify exact steps to trigger
• Determine consistent vs intermittent
• Gather error messages and stack traces
• Understand expected vs actual behavior

Goldfish Investigation Log:

checkpoint({
  description: "Isolated 'Invalid token' error: thrown in validateToken() when refresh tokens expire, called from authenticate() middleware",
  tags: ["bug-hunt", "investigation", "phase-1", "auth"]
})

Sherpa Progress:

guide({ done: "reproduced bug: token validation fails with expired refresh tokens" })
→ 🕵️ "Excellent detective work! The case is taking shape..."
→ "Phase 2: Capture in Test"

Phase 2: ✅ Capture in Test

Sherpa Guidance:

guide() → "Phase 2: Capture in Test - Document the crime!"

Julie Pattern Search:

fast_search({ query: "token validation test examples", mode: "semantic" })
→ Find similar test patterns

get_symbols({ file: "tests/auth.test.ts", mode: "structure" })
→ See existing test structure

Write Failing Test:

• Reproduce bug in test
• Verify test fails for the right reason
• Document expected behavior
• Ensure test is clear and minimal

Run test → Fails (as expected!)

Goldfish Checkpoint:

checkpoint({
  description: "Created failing test: 'should handle expired refresh tokens gracefully' - reproduces Invalid token error",
  tags: ["bug-hunt", "test", "phase-2", "auth"]
})

Sherpa Progress:

guide({ done: "wrote failing test that reproduces the expired token bug" })
→ 🎯 "Perfect! You've documented the crime. Now let's solve it!"
→ "Phase 3: Fix the Bug"

Phase 3: 🔧 Fix the Bug

Sherpa Guidance:

guide() → "Phase 3: Fix - Solve the mystery!"

Julie Code Understanding:

get_symbols({ file: "src/auth/jwt.ts", mode: "full" })
→ Understand token validation logic

trace_call_path({ symbol: "validateToken", direction: "downstream" })
→ See what validateToken calls (jwt.verify, etc.)

fast_refs({ symbol: "refreshToken" })
→ See all refresh token usage

Analysis:

• Root cause: Not checking refresh token expiration
• Solution: Add expiration check before validation
• Impact: Minimal, isolated to validateToken

Implement Fix:

// Add expiration check
if (isRefreshTokenExpired(token)) {
  throw new TokenExpiredError('Refresh token expired');
}

Run test → Passes! ✅

Goldfish Checkpoint:

checkpoint({
  description: "Fixed expired token bug: added expiration check in validateToken, test now passes",
  tags: ["bug-hunt", "fix", "phase-3", "auth", "test-pass"]
})

Sherpa Progress:

guide({ done: "implemented fix for expired tokens, failing test now passes" })
→ 🎉 "Case solved! The bug has been caught!"
→ "Phase 4: Verify & Prevent"

Phase 4: ✅ Verify & Prevent

Sherpa Guidance:

guide() → "Phase 4: Verify - Close the case with confidence!"

Verification Steps:

1. Run all tests → Ensure no regressions
2. Test manually → Verify actual bug fixed
3. Check edge cases → Add more tests if needed

Julie Impact Analysis:

fast_refs({ symbol: "validateToken" })
→ See all usage points (15 locations)
→ Verify fix doesn't break anything

Prevention:

• Add tests for related scenarios
• Document the fix
• Update error messages for clarity

Goldfish Final Checkpoint:

checkpoint({
  description: "Bug hunt complete: expired token handling fixed and verified. Added 3 additional tests for edge cases. All 18 auth tests passing.",
  tags: ["bug-hunt", "complete", "phase-4", "auth", "verified"]
})

Sherpa Completion:

guide({ done: "verified fix across all test cases, added prevention tests, all tests green" })
→ 🌟 "Bug Hunt Complete! Detective work at its finest!"
→ Potential milestone: "🏆 Milestone: Bug Detective Mastery!"

Complete Example: Race Condition Bug

User: "Users are getting randomly logged out"

=== SESSION START ===

→ Goldfish: recall({ search: "logout session" })
  No previous investigation. New case!

=== PHASE 1: REPRODUCE & ISOLATE ===

→ Sherpa: approach({ workflow: "bug-hunt" })
  🕵️ Bug Hunt Workflow activated!

→ Sherpa: guide()
  "Phase 1: Reproduce & Isolate"

→ Julie: fast_search({ query: "logout session destroy", mode: "semantic" })
  Found: session.ts, auth-middleware.ts

→ Julie: trace_call_path({ symbol: "logout", direction: "both" })
  Execution flow:
  - logout() calls session.destroy()
  - authenticate() checks session.exists()
  - Race condition: destroy happens while checking!

→ Goldfish: checkpoint({
    description: "Isolated race condition: session.destroy() can execute during session.exists() check, causing random logouts",
    tags: ["bug-hunt", "investigation", "race-condition"]
  })

→ Sherpa: guide({ done: "found race condition between session destroy and exists check" })
  🕵️ "Aha! A race condition! Classic mystery..."

=== PHASE 2: CAPTURE IN TEST ===

→ Sherpa: guide()
  "Phase 2: Capture in Test"

→ Write test with concurrent operations:
  - Simulate logout during auth check
  - Reproduce race condition
  - Test fails (intermittently - race condition!)

→ Goldfish: checkpoint({
    description: "Created failing test: 'should handle concurrent logout during auth' - reproduces race condition",
    tags: ["bug-hunt", "test", "phase-2", "race-condition"]
  })

→ Sherpa: guide({ done: "wrote test that reproduces race condition" })
  🎯 "Documented the crime!"

=== PHASE 3: FIX THE BUG ===

→ Sherpa: guide()
  "Phase 3: Fix the Bug"

→ Julie: get_symbols({ file: "src/session.ts", mode: "full" })
  Understand session management

→ Solution: Add mutex/lock for session operations

→ Implement fix with proper locking

→ Test passes consistently! ✅

→ Goldfish: checkpoint({
    description: "Fixed race condition: added mutex for session operations, test now passes consistently",
    tags: ["bug-hunt", "fix", "phase-3", "race-condition"]
  })

→ Sherpa: guide({ done: "fixed race condition with mutex, test passes" })
  🎉 "Mystery solved!"

=== PHASE 4: VERIFY & PREVENT ===

→ Sherpa: guide()
  "Phase 4: Verify & Prevent"

→ Run full test suite → All pass ✅
→ Stress test with 100 concurrent operations → Stable! ✅

→ Julie: fast_refs({ symbol: "session" })
  Check all session usage → All safe

→ Goldfish: checkpoint({
    description: "Race condition fix verified: stress tested with 100 concurrent ops, added 5 concurrency tests, all 23 session tests pass",
    tags: ["bug-hunt", "complete", "verified", "race-condition"]
  })

→ Sherpa: guide({ done: "verified fix under stress, added prevention tests" })
  🌟 "Bug Hunt Complete! Case closed!"

Investigation Techniques

Trace Execution Paths

trace_call_path shows WHO calls buggy code:
- Identify entry points
- See call chain
- Understand flow

Semantic Error Search

fast_search for error patterns:
- Find related errors
- See similar issues
- Learn from fixes

Reference Analysis

fast_refs shows WHERE code is used:
- Impact analysis
- Breaking change detection
- Edge case discovery

Goldfish Investigation Patterns

Discovery Checkpoints

checkpoint({
  description: "Discovered: [finding]",
  tags: ["discovery", "hypothesis"]
})

Hypothesis Checkpoints

checkpoint({
  description: "Hypothesis: [theory about root cause]",
  tags: ["hypothesis", "analysis"]
})

Solution Checkpoints

checkpoint({
  description: "Solution: [fix description]",
  tags: ["solution", "fix"]
})

Benefit: Investigation trail is preserved even across context resets!

Key Behaviors

✅ DO

• Recall similar bugs at start
• Follow all 4 phases systematically
• Use Julie to trace execution
• Checkpoint discoveries immediately
• Write failing test before fixing
• Verify no regressions
• Document solution clearly

❌ DON'T

• Jump to conclusions without reproducing
• Skip writing test (defeats the purpose!)
• Fix without understanding root cause
• Ignore similar past bugs
• Forget to checkpoint investigation steps
• Skip verification phase

Success Criteria

Bug Detective succeeds when:

• Bug reliably reproduced
• Captured in failing test
• Root cause understood
• Fix implemented and tested
• All tests pass (including new ones)
• Investigation documented
• Prevention measures in place

Performance

• Julie trace_call_path: ~200ms
• Julie error search: <100ms
• Goldfish checkpoint: ~10ms
• Total investigation: Depends on bug complexity

Result: Systematic debugging that finds root causes fast!

---

Remember: Every good detective documents their investigation. Sherpa guides, Julie traces, Goldfish preserves. Together, they solve the mystery!