---

name: find-bug-root-cause description: Deep investigation to find actual root cause (not just symptoms) model: sonnet

Root Cause Analysis Protocol

When a feature is broken, don't just add logging - find and fix the ACTUAL problem.

Methodology

1. Understand the Symptom:

   • What does the user see/experience?
   • What SHOULD happen?
   • What ACTUALLY happens?

2. Trace the Data Flow:

   • Follow code execution from UI → ViewModel → Service → Backend
   • Check each layer for failures
   • Use breakpoint logic (mental trace)

3. Check Dependencies:

   • Is the service initialized? (DIContainer.shared.service)
   • Are databases/indexes ready?
   • Are async operations completing?
   • Are errors being swallowed?

4. Find the Bug:

   • Don't stop at "add try/catch" or "add logging"
   • Find the EXACT line where logic fails
   • Understand WHY it fails

5. Fix It Properly:

   • Fix root cause, not symptoms
   • Add defensive checks only AFTER fixing core issue
   • Test the fix logic

6. Verify:

   • Does the fix address the root cause?
   • Are there edge cases?
   • Will this prevent recurrence?

Example: "Search returns no results"

❌ Bad approach:

Copy// Just add logging
AppLog.info("Search started")
let results = await search(query)
AppLog.info("Search returned \(results.count) results")

✅ Good approach:

Copy// Find WHY search returns nothing:
// 1. Is ScriptureDatabase initialized? → Check init
// 2. Are indexes built? → Check index creation
// 3. Is query being processed? → Check query transformation
// 4. FIX the actual issue (e.g., index not built on first launch)

// THEN add logging to prevent future issues

Return the root cause and the actual fix that solves it.