# Find Bug Root Cause

> Deep investigation to find actual root cause (not just symptoms)

- Skill: `majiayu000/find-bug-root-cause` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/find-bug-root-cause`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/find-bug-root-cause/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/find-bug-root-cause

---


# 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:**
```swift
// Just add logging
AppLog.info("Search started")
let results = await search(query)
AppLog.info("Search returned \(results.count) results")
```

✅ **Good approach:**
```swift
// 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.**