RCA Workflow

Root Cause Analysis workflow for bug tickets, documenting cause and prevention before implementing the fix.

When to Use

Use RCA for bugs where understanding the root cause prevents recurrence. Skip for trivial bugs.

Prerequisites

CLI installed and authenticated
Bug ticket assigned to you

The RCA Flow

# 1. Start bug ticket (auto-creates RCA template)
wseng start LAMBDA-12345

# 2. Generate RCA analysis
wseng rca

# 3. Review and complete .context/rca/rca.yaml

# 4. Save RCA
wseng ws save-rca

# 5. Implement fix
wseng rca-fix

# 6. Continue normal flow (commit, changelog, demo)

RCA Structure

The .context/rca/rca.yaml file contains:

rootCause: |
    The specific cause of the bug

whyItHappened: |
    Explanation of why this cause led to the bug

preventionMeasures: |
    Specific steps to prevent recurrence

fix: |
    Brief description of the implemented fix

relatedTickets:
    - LAMBDA-98765

What Makes a Good RCA

Root Cause: Be specific, not vague.

❌ Bad: "The code had a bug"

✅ Good: "Null pointer in UserService.getProfile() at line 45 when user.email is null"

Prevention Measures: Actionable steps, not generic advice.

❌ Bad: "Write better code" or "Add more tests"

✅ Good:

preventionMeasures: |
    1. Add NOT NULL constraint to users.email column
    2. Add validation in registration API
    3. Add unit test covering null email case
    4. Add linting rule to flag unguarded property access

Commands

Generate RCA with demo video:

wseng rca --demo-video-url https://drive.google.com/file/d/abc123

Load existing RCA for reference:

wseng ws load-rca LAMBDA-98765

Save RCA:

wseng ws save-rca

Implement fix based on RCA:

wseng rca-fix

Common Pitfalls

❌ Bad: Fixing symptoms instead of root cause

Bug: Error message "Invalid date format"

rootCause: "Date validation was too strict"
fix: "Relaxed date validation"

This makes the symptom disappear but misses the real issue.