Root Cause Analysis Protocol
When a feature is broken, don't just add logging - find and fix the ACTUAL problem.
Methodology
- Understand the Symptom:
- What does the user see/experience? - What SHOULD happen? - What ACTUALLY happens?
- Trace the Data Flow:
- Follow code execution from UI → ViewModel → Service → Backend - Check each layer for failures - Use breakpoint logic (mental trace)
- Check Dependencies:
- Is the service initialized? (DIContainer.shared.service) - Are databases/indexes ready? - Are async operations completing? - Are errors being swallowed?
- Find the Bug:
- Don't stop at "add try/catch" or "add logging" - Find the EXACT line where logic fails - Understand WHY it fails
- Fix It Properly:
- Fix root cause, not symptoms - Add defensive checks only AFTER fixing core issue - Test the fix logic
- Verify:
- Does the fix address the root cause? - Are there edge cases? - Will this prevent recurrence?
Example: "Search returns no results"
❌ Bad approach:
// Just add logging
AppLog.info("Search started")
let results = await search(query)
AppLog.info("Search returned \(results.count) results")✅ Good approach:
// 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 issuesReturn the root cause and the actual fix that solves it.