investigate-root-cause Skill

investigate-root-cause

Deep investigation to find the root cause of a validated customer issue using code analysis and debugging.

When to Use

After validating that a customer issue is reproducible
When Playwright validation shows consistent failure
When error messages need tracing to source code
Before creating fix specifications for Dev agent

Quick Start

Review validation evidence (errors, screenshots, logs)
Search codebase for error signatures
Trace through call paths and data flow
Identify affected components
Document root cause and affected areas

Purpose

After validating that a customer issue is reproducible, investigate the codebase to identify the exact cause, affected components, and potential fixes.

SEQUENTIAL Task Execution

1. Review Validation Evidence

evidence_review:
  - Console errors from Playwright validation
  - Network failures and API responses  
  - Screenshots showing the issue state
  - Timing data (performance issues)
  - Stack traces if available

2. Search for Error Signatures

Use grep/search tools to find related code:

search_patterns:
  error_messages:
    - Search for exact error text from console
    - Look for exception messages
    - Find logging statements near the error
  
  component_search:
    - Identify UI component from screenshots
    - Search for element IDs/classes
    - Find event handlers for user actions
  
  api_endpoints:
    - Locate controller/endpoint from network logs
    - Find service methods being called
    - Trace database queries involved

3. Analyze Code Flow

code_analysis:
  entry_point:
    - Start from user action (button click, form submit)
    - Trace through event handlers
    - Follow API calls
  
  data_flow:
    - Track data from input to processing
    - Identify transformations
    - Find validation points
  
  error_points:
    - Locate try/catch blocks
    - Find error handling logic
    - Identify missing error cases

4. Check Recent Changes

change_investigation:
  git_history:
    - Check commits to affected files (last 30 days)
    - Review PRs that touched this area
    - Look for related deployments
  
  dependency_updates:
    - Package updates that might affect behavior
    - API version changes
    - Database schema modifications

5. Root Cause Identification

Common Root Cause Patterns

Race Conditions:

// PROBLEM: Not waiting for async operation
public async Task ProcessPayment()
{
    StartPaymentProcess(); // Missing await!
    return RedirectToSuccess(); // Happens before payment completes
}

Null Reference:

// PROBLEM: Not checking for null
var user = await GetUser(id);
var email = user.Email; // Crashes if user is null

Timeout Issues:

// PROBLEM: Default timeout too short
var client = new HttpClient(); // 100 second default
var response = await client.GetAsync(slowEndpoint); // Times out

State Management:

// PROBLEM: State not updating correctly
setState(newState); // Async operation
doSomethingWithState(state); // Uses old state

6. Document Findings

root_cause_report:
  issue_summary: "Payment spinner runs indefinitely"
  
  root_cause:
    description: "Async payment process not awaited"
    file: "PaymentController.cs"
    line: 145
    method: "ProcessPayment"
    
  code_snippet: |
    // Line 145 - Missing await
    StartPaymentProcess(payment);
    return RedirectToAction("Success");
    
  why_it_fails:
    - "StartPaymentProcess is async but not awaited"
    - "Redirect happens immediately"
    - "Frontend polls for completion that never comes"
    
  when_introduced:
    commit: "abc123def"
    date: "2024-01-10"
    pr: "#4567"
    author: "developer@example.com"

7. Impact Analysis

impact_assessment:
  direct_impact:
    - Files that need modification
    - Methods that need updates
    - Tests that will be affected
  
  side_effects:
    - Other features using same code
    - Performance implications
    - Security considerations
  
  risk_level:
    low: "Isolated change, well-tested area"
    medium: "Affects shared components"
    high: "Core system change, multiple dependencies"

8. Investigation Queries

Find Error Patterns

# Search for error message
grep -r "spinner" --include="*.cs" --include="*.js"

# Find recent changes to payment flow
git log -p --since="30 days ago" -- "*Payment*"

# Locate async issues
grep -r "StartPayment" --include="*.cs" | grep -v "await"

Analyze Dependencies

# Check package versions
cat package.json | grep -A2 -B2 "react"

# Find API calls
grep -r "fetch.*payment" --include="*.js"

Success Criteria

[ ] Root cause identified with specific code location
[ ] Understanding of why the issue occurs
[ ] Timeline of when issue was introduced
[ ] Impact assessment completed
[ ] Fix approach identified

Output

Root cause analysis document
Affected code locations
Recommended fix approach
Risk assessment for changes

Agent Skills: investigate-root-cause

Install this agent skill to your local

Skill Files