error-explanation-generator

# Error Explanation Generator

Analyze test failures and provide clear explanations with actionable fixes.

## Core Capabilities

This skill helps debug failed tests by:

1. **Parsing error messages** - Extract key information from test output
2. **Identifying root causes** - Determine why tests fail
3. **Explaining clearly** - Translate technical errors into understandable language
4. **Providing fixes** - Suggest concrete, actionable solutions
5. **Recognizing patterns** - Detect common error categories across frameworks

## Error Analysis Workflow

### Step 1: Gather Error Context

Collect all relevant information:

**Essential Information:**
- Complete error message and stack trace
- Test framework being used (pytest, jest, junit, etc.)
- Test code that failed
- Code being tested (if accessible)
- Programming language

**Additional Context (if available):**
- Recent code changes
- Environment details (OS, language version, dependencies)
- Test configuration files

**How to gather:**
```bash
# Python pytest
pytest -v --tb=long

# JavaScript/TypeScript jest
npm test -- --verbose

# Java junit
mvn test -X

# Go tests
go test -v
```

### Step 2: Parse and Categorize the Error

Identify the error category using `references/error_patterns.md`:

**Common Categories:**

1. **Assertion Failures** - Expected vs actual value mismatch
2. **Exceptions/Errors** - Runtime errors during test execution
3. **Timeout Errors** - Tests taking too long
4. **Setup/Teardown Failures** - Fixture or initialization issues
5. **Import/Dependency Errors** - Missing modules or broken imports
6. **Type Errors** - Type mismatches in typed languages
7. **Mock/Stub Issues** - Problems with test doubles
8. **Configuration Errors** - Test framework or build config issues
9. **Compilation Errors** - Syntax or build failures
10. **Flaky Test Issues** - Intermittent failures

### Step 3: Extract Key Information

Pull out critical details:

**From Error Message:**
- Error type (AssertionError, TypeError, NullPointerException, etc.)
- Expected vs actual values
- Error description
- Line numbers where error occurred

**From Stack Trace:**
- Failure point in test code
- Failure point in source code
- Call chain leading to error

**Example Extraction:**

```
FAILED tests/test_user.py::test_create_user - AssertionError: assert 201 == 200
```

**Extracted:**
- Test file: `tests/test_user.py`
- Test name: `test_create_user`
- Error type: `AssertionError`
- Expected: `200`
- Actual: `201`

### Step 4: Identify Root Cause

Analyze why the error occurred:

**Questions to Ask:**
- What was the test expecting?
- What actually happened?
- Why did the actual behavior differ from expected?
- Is this a test bug or a code bug?

**Common Root Causes:**
- Logic error in implementation
- Incorrect test expectations
- Missing or wrong test data
- Race conditions or timing issues
- Environmental differences
- Outdated mocks or fixtures
- Dependency version conflicts

### Step 5: Provide Explanation

Structure the explanation clearly:

```markdown
## Error Summary

[One-sentence description of what went wrong]

## What Happened

[Explain the error in plain language]

**Expected:** [What the test expected to happen]
**Actual:** [What actually happened]

## Root Cause

[Explain why this happened - the underlying issue]

## How to Fix

### Option 1: [Most likely fix] ⭐

[Specific code change or action to take]

```[language]
// Before
[problematic code]

// After
[fixed code]
```

**Why this works:** [Brief explanation]

### Option 2: [Alternative fix]

[Another possible solution if Option 1 doesn't apply]

## Verification

[How to verify the fix works]

```bash
[command to run test]
```

## Prevention

[How to avoid this error in the future]
```

### Step 6: Suggest Next Steps

Provide actionable guidance:

**If fix is clear:**
- Show exact code change
- Provide test command to verify
- Mention related tests to check

**If diagnosis needs more info:**
- Suggest debugging steps
- Recommend logging/print statements to add
- Propose code to inspect

**If issue is environmental:**
- Suggest dependency checks
- Recommend configuration verification
- Propose environment comparison

## Error Pattern Examples

### Example 1: Assertion Failure (Python/pytest)

**Error Output:**
```
FAILED tests/test_calculator.py::test_divide - AssertionError: assert 2.5 == 2
```

**Analysis:**

```markdown
## Error Summary
Test expected integer division but got float division result.

## What Happened

**Expected:** `2` (integer)
**Actual:** `2.5` (float)

The test `test_divide` called a divide function with arguments that produce
a decimal result (e.g., 5 / 2 = 2.5) but expected an integer result.

## Root Cause

The implementation uses true division (`/`) which returns floats in Python 3,
but the test expects integer division behavior.

## How to Fix

### Option 1: Update implementation to use integer division ⭐

```python
# Before
def divide(a, b):
    return a / b

# After
def divide(a, b):
    return a // b  # Integer division
```

**Why this works:** The `//` operator performs floor division, returning
integers when both operands are integers.

### Option 2: Update test to expect float result

```python
# Before
assert divide(5, 2) == 2

# After
assert divide(5, 2) == 2.5
```

Use this if float division is the intended behavior.

## Verification

```bash
pytest tests/test_calculator.py::test_divide -v
```

## Prevention

- Clarify division requirements in function documentation
- Use type hints: `def divide(a: int, b: int) -> int:`
- Add test cases for both integer and float division scenarios
```

### Example 2: TypeError (JavaScript/Jest)

**Error Output:**
```
TypeError: Cannot read property 'name' of undefined
    at getUserName (src/user.js:5:20)
    at Object.<anonymous> (tests/user.test.js:10:22)
```

**Analysis:**

```markdown
## Error Summary
Attempted to access property 'name' on undefined user object.

## What Happened

**Expected:** User object with 'na