tomevault-io 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:
- Run all tests → Ensure no regressions
- Test manually → Verify actual bug fixed
- 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!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.