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 issues

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