root-cause-analyzer

Root Cause Analyzer Skill

Purpose

Systematically identifies root causes of complex problems using the 5 Whys methodology from docs/5-WHYS-METHODOLOGY.md. Documents findings in docs/development-learnings/ and updates Knowledge Base (docs/kb/) using make kb-pattern. Implements FR-009 from the feature specification.

Knowledge Base Integration

IMPORTANT: Before starting root cause analysis, check the Knowledge Base for existing patterns.

Pre-Analysis KB Check

from scripts.kb.search import kb_search, kb_get_pattern

# Search for similar issues
results = kb_search(
    query="[error message or symptom]",
    category="[ARCH/DB/API/TEST/etc]",
    min_quality_score=60,
    limit=5
)

if results:
    print(f"Found {len(results)} existing patterns!")
    # Review top pattern
    pattern = kb_get_pattern(results[0].id)
    if pattern:
        # Apply existing solution instead of re-analyzing
        print("Applying existing root cause analysis from KB")
else:
    print("No existing patterns found. Proceeding with new 5 Whys analysis")

When to Check KB

1. Before starting 5 Whys: Search for error messages, symptoms, or similar problems
2. During analysis: Browse relevant categories (ARCH, DB, API, TEST, ERROR) for design patterns
3. After finding root cause: Search again to see if this is a known systemic issue
4. Before documenting: Check if similar pattern exists to avoid duplication

What to Search For

• Exact error messages: Copy error text into search query
• Symptom keywords: "timeout", "connection pool", "race condition", etc.
• Technology + problem: "postgresql connection pool exhausted"
• Pattern category: Use category filter to narrow results

If Pattern Found

1. Review the existing pattern's 5 Whys analysis
2. Check if root cause matches current issue
3. Apply existing solution if applicable
4. Update pattern usage count if applied
5. Add cross-reference in your documentation

If No Pattern Found