Root Cause Analysis: GitHub Issue #$ARGUMENTS

Objective

Investigate GitHub issue #$ARGUMENTS from this repository, identify the root cause, and document findings for future implementation.

Prerequisites:

• Working in a local Git repository with GitHub origin

• GitHub CLI installed and authenticated (gh auth status )

• Valid GitHub issue ID from this repository

Investigation Process

1. Fetch GitHub Issue Details

Use GitHub CLI to retrieve issue information:

gh issue view $ARGUMENTS

This fetches:

• Issue title and description

• Reporter and creation date

• Labels and status

• Comments and discussion

2. Search Codebase

Identify relevant code:

• Search for components mentioned in issue

• Find related functions, classes, or modules

• Check similar implementations

• Look for patterns or recent changes

Use grep/search to find:

• Error messages from issue

• Related function names

• Component identifiers

3. Review Recent History

Check recent changes to affected areas: !git log --oneline -20 -- [relevant-paths]

Look for:

• Recent modifications to affected code

• Related bug fixes

• Refactorings that might have introduced the issue

4. Investigate Root Cause

Analyze the code to determine:

• What is the actual bug or issue?

• Why is it happening?

• What was the original intent?

• Is this a logic error, edge case, or missing validation?

• Are there related issues or symptoms?

Consider:

• Input validation failures

• Edge cases not handled

• Race conditions or timing issues

• Incorrect assumptions

• Missing error handling

• Integration issues between components

5. Assess Impact

Determine:

• How widespread is this issue?

• What features are affected?

• Are there workarounds?

• What is the severity?

• Could this cause data corruption or security issues?

6. Propose Fix Approach

Design the solution:

• What needs to be changed?

• Which files will be modified?

• What is the fix strategy?

• Are there alternative approaches?

• What testing is needed?

• Are there any risks or side effects?

Output: Create RCA Document

Save analysis as: docs/rca/issue-$ARGUMENTS.md

Required RCA Document Structure

Root Cause Analysis: GitHub Issue #$ARGUMENTS

Issue Summary

• GitHub Issue ID: #$ARGUMENTS
• Issue URL: [Link to GitHub issue]
• Title: [Issue title from GitHub]
• Reporter: [GitHub username]
• Severity: [Critical/High/Medium/Low]
• Status: [Current GitHub issue status]

Problem Description

[Clear description of the issue]

Expected Behavior: [What should happen]

Actual Behavior: [What actually happens]

Symptoms:

• [List observable symptoms]

Reproduction

Steps to Reproduce:

1. [Step 1]
2. [Step 2]
3. [Observe issue]

Reproduction Verified: [Yes/No]

Root Cause

Affected Components

• Files: [List of affected files with paths]
• Functions/Classes: [Specific code locations]
• Dependencies: [Any external deps involved]

Analysis

[Detailed explanation of the root cause]

Why This Occurs: [Explanation of the underlying issue]

Code Location:

[File path:line number] [Relevant code snippet showing the issue]

Related Issues

• [Any related issues or patterns]

Impact Assessment

Scope:

• [How widespread is this?]

Affected Features:

• [List affected features]

Severity Justification: [Why this severity level]

Data/Security Concerns: [Any data corruption or security implications]

Proposed Fix

Fix Strategy

[High-level approach to fixing]

Files to Modify

1. [file-path]

   • Changes: [What needs to change]
   • Reason: [Why this change fixes it]

2. [file-path]

   • Changes: [What needs to change]
   • Reason: [Why this change fixes it]

Alternative Approaches

[Other possible solutions and why the proposed approach is better]

Risks and Considerations

• [Any risks with this fix]
• [Side effects to watch for]
• [Breaking changes if any]

Testing Requirements

Test Cases Needed:

1. [Test case 1 - verify fix works]
2. [Test case 2 - verify no regression]
3. [Test case 3 - edge cases]

Validation Commands:

[Exact commands to verify fix]

Implementation Plan

[Brief overview of implementation steps]

This RCA document should be used by /implement-fix
 command.

Next Steps

- Review this RCA document

- Run: /implement-fix $ARGUMENTS
 to implement the fix

- Run: /commit
 after implementation complete