SPECIFICATION
- [ ] What should the feature do? (spec, user story, acceptance criteria)
- [ ] What behavior is expected?

OBSERVED BEHAVIOR
- [ ] What actually happens?
- [ ] Error messages (exact text)
- [ ] Logs (relevant sections)

REPRODUCTION
- [ ] Steps to reproduce
- [ ] Input data that triggers the bug
- [ ] Environment (Python version, OS, dependencies)

CONTEXT
- [ ] When did it last work? (if ever)
- [ ] What changed recently?
- [ ] Is it intermittent or consistent?

## Bug Report

**Expected Behavior**:
[What should happen according to spec]

**Actual Behavior**:
[What is happening]

**Error/Logs**:

**Reproduction Steps**:
1. [First step]
2. [Second step]
3. [Step where failure occurs]

**Environment**:
- Python: [version]
- OS: [os]
- Relevant packages: [list]

**Recent Changes**:
[What changed before this started happening]

WORKING
- [ ] [Feature X works correctly]
- [ ] [Feature Y works correctly]

NOT WORKING
- [ ] [Feature Z fails with error]
- [ ] [Feature W produces wrong output]

UNKNOWN
- [ ] [Feature V not tested yet]

Questions to answer:
1. Is this a regression or never worked?
2. Does it fail for all inputs or specific ones?
3. Does it fail in all environments or specific ones?
4. Is the failure consistent or intermittent?
5. What's the smallest reproduction case?

# Minimal reproduction case
# Goal: Smallest code that demonstrates the bug

def test_reproduction():
    """Minimal reproduction of the bug."""
    # Setup
    input_data = {"key": "value"}  # Specific input that triggers bug

    # Action
    result = buggy_function(input_data)

    # Expected vs Actual
    assert result == expected, f"Got {result}, expected {expected}"

## Hypothesis List

H1: [Description of potential cause]
    Evidence for: [what supports this]
    Evidence against: [what contradicts this]
    Test: [how to verify]

H2: [Description of potential cause]
    Evidence for: [what supports this]
    Evidence against: [what contradicts this]
    Test: [how to verify]

H3: [Description of potential cause]
    Evidence for: [what supports this]
    Evidence against: [what contradicts this]
    Test: [how to verify]

1. INPUT: What data enters the function?
   - Log: input values, types, shapes

2. PROCESSING: What transformations occur?
   - Add debug logging at each step
   - Check intermediate values

3. OUTPUT: What comes out?
   - Compare actual vs expected output
   - Check return type and structure

4. SIDE EFFECTS: What else changes?
   - Database writes
   - File system changes
   - External API calls
   - Global state modifications

import logging

logger = logging.getLogger(__name__)

def investigate_function(data: InputType) -> OutputType:
    logger.debug(f"INPUT: data={data!r}, type={type(data)}")

    # Step 1
    intermediate1 = process_step1(data)
    logger.debug(f"STEP1: intermediate1={intermediate1!r}")

    # Step 2
    intermediate2 = process_step2(intermediate1)
    logger.debug(f"STEP2: intermediate2={intermediate2!r}")

    # Step 3
    result = process_step3(intermediate2)
    logger.debug(f"OUTPUT: result={result!r}, type={type(result)}")

    return result

def test_hypothesis_1():
    """Test H1: [hypothesis description]"""
    # Setup to isolate this hypothesis
    # ...

    # Action that should reveal if H1 is correct
    # ...

    # Assertion that confirms or refutes H1
    # If this passes, H1 is likely correct
    # If this fails, H1 is refuted

## Root Cause Evidence

**Confirmed Root Cause**: [description]

**Evidence**:
1. [File:line] - [what this shows]
2. [Log entry] - [what this shows]
3. [Test result] - [what this shows]

**Why This Causes the Bug**:
[Explanation of the causal chain from root cause to symptom]

**Eliminated Hypotheses**:
- H2: Ruled out because [evidence]
- H3: Ruled out because [evidence]

## Fix Specification

**Root Cause**: [concise description]
**Location**: [file:line range]

**Fix Approach**:
[Description of what needs to change]

**Risks**:
- [Potential side effect 1]
- [Potential side effect 2]

**Test Coverage**:
- [ ] Test for original bug (regression test)
- [ ] Test for edge cases
- [ ] Test for potential side effects

BEFORE FIX
- [ ] Root cause identified with evidence
- [ ] Minimal reproduction exists
- [ ] Test coverage plan created

DURING FIX
- [ ] Fix addresses root cause (not symptoms)
- [ ] Fix is minimal (no scope creep)
- [ ] Regression test written first

AFTER FIX
- [ ] Regression test passes
- [ ] Existing tests still pass
- [ ] Edge case tests added
- [ ] Code review if significant change

def test_bug_12345_description():
    """Regression test for bug #12345.

    Bug: [brief description of the original bug]
    Root cause: [what was wrong]
    Fix: [what was changed]
    """
    # Arrange: Setup that triggered the bug
    input_data = create_problematic_input()

    # Act: The operation that failed
    result = fixed_function(input_data)

    # Assert: Verify correct behavior
    assert result == expected_output
    # Also verify the specific fix worked
    assert result.specific_field == expected_value

## Bug Investigation Report

**Issue**: [Brief description]
**Status**: [Investigating | Root Cause Found | Fixed | Cannot Reproduce]

### Problem Statement

**Expected**: [spec behavior]
**Actual**: [observed behavior]
**Impact**: [who/what is affected]

### Investigation Timeline

1. [timestamp] - [action taken] - [result]
2. [timestamp] - [action taken] - [result]
3. [timestamp] - [action taken] - [result]

### Hypotheses

| # | Hypothesis | Status | Evidence |
|---|------------|--------|----------|
| H1 | [description] | Confirmed/Refuted | [evidence] |
| H2 | [description] | Confirmed/Refuted | [evidence] |

### Root Cause

**Location**: [file:line]
**Description**: [what's wrong and why]
**Evidence**: [how we know this is the cause]

### Fix

**Approach**: [what will be changed]
**Files Modified**: [list]
**Tests Added**: [list]

### Verification

- [ ] Bug no longer reproduces
- [ ] Regression test passes
- [ ] Existing tests pass
- [ ] Edge cases covered

# Bug: AttributeError: 'NoneType' has no attribute 'x'
# Cause: Function returns None unexpectedly

# Investigation
result = get_something()
print(f"result is None: {result is None}")  # Check this first

# Fix: Add proper None handling
if (result := get_something()) is None:
    raise ValueError("Expected result but got None")
return result.x

# Bug: List accumulates across calls
def buggy(items=[]):  # WRONG: mutable default
    items.append(1)
    return items

# Fix
def fixed(items: list | None = None) -> list:
    if items is None:
        items = []
    items.append(1)
    return items

# Bug: Coroutine never executed
async def fetch_data():
    return await api_call()

# WRONG: Missing await
result = fetch_data()  # Returns coroutine, not result

# Fix
result = await fetch_data()

# Bug: ImportError or circular import
# Investigation: Check import order and dependencies

# Fix: Use local imports for circular dependencies
def function_that_needs_other_module():
    from .other_module import OtherClass  # Local import
    return OtherClass()