RCA Workflow

Document the cause and prevention steps for a bug before implementing its 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

wseng start-ticket <ticket-key>
wseng ws create-blank-rca

Review and complete .context/rca/rca.yaml, then save the RCA:

wseng ws save-rca

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

Create a blank RCA:

wseng ws create-blank-rca

Save the RCA:

wseng ws save-rca

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.

✅ Good:

rootCause: "Client sends dates in local timezone, API expects UTC"
whyItHappened: |
    Frontend DatePicker defaults to local timezone.
    API validation assumes UTC.
    No timezone conversion between client and server.
fix: "Convert dates to UTC in client before sending to API"