git status
git branch --show-current

Where should I work on this bug fix?

**Option A: New worktree** (Recommended for parallel work)
- Creates isolated workspace
- Safe if the fix might be experimental
- Allows multiple agents to work simultaneously

**Option B: Current worktree**
- Simpler, no setup overhead
- Good for quick, focused fixes

# Create branch and worktree
git worktree add ../cernel-backend-bugfix-<short-desc> -b fix/<short-description>

# Copy environment files (required - these are gitignored)
cp .env* ../cernel-backend-bugfix-<short-desc>/

# Copy local Claude settings if they exist
cp -r .claude/settings.local.json ../cernel-backend-bugfix-<short-desc>/.claude/ 2>/dev/null || true

# Navigate to worktree
cd ../cernel-backend-bugfix-<short-desc>

# Install dependencies (venv is gitignored, so must be recreated)
uv sync --all-packages

git checkout -b fix/<short-description>

Read the file and lines from the stack trace:
- The exact line that raised the error
- The surrounding function/method
- The class or module context

Task tool with Explore agent (thoroughness: "very thorough"):

Investigate this error:

**Error**: [Error type and message]
**Location**: [File:line from stack trace]
**Call chain**: [Key functions in the trace]

Find:
1. The code path that leads to this error
2. What conditions trigger this error
3. Related code that might be involved
4. Similar patterns elsewhere that work correctly
5. Recent changes to this area (if apparent)

Focus on understanding WHY this error occurs, not just WHERE.

## Root Cause Analysis

**Error**: [Type]: [Message]

**Location**: `path/to/file.py:123` in `function_name()`

**Root Cause**:
[Clear, concise explanation of why this error occurs]

**Trigger Condition**:
[What specific input/state causes this]

**Evidence**:
- [Code reference supporting the hypothesis]
- [Logic flow that leads to the error]

## Bug Analysis: [Brief Title]

### Error
[Original error/stack trace]

### Root Cause
[Clear explanation of why this happens]

### Affected Code
- `path/to/file.py:123` - [What's wrong here]

### Trigger
[How to reproduce this]

---

Does this analysis match your understanding of the bug?

# Bug reproduction script
# Run with: python -c "..."

from module import function

# Setup that triggers the bug
result = function(problematic_input)
# Expected: X
# Actual: raises ErrorType

# Reproduce with curl or httpie
curl -X POST localhost:8000/endpoint \
  -H "Content-Type: application/json" \
  -d '{"problematic": "input"}'

def test_<descriptive_name>_<expected_behavior>(self) -> None:
    """
    Regression test for [bug description].

    The bug occurred when [trigger condition].
    Fixed by [will be filled after fix].
    """
    # Arrange
    # Set up the conditions that trigger the bug

    # Act
    # Perform the action that caused the error

    # Assert
    # Verify the CORRECT behavior (what SHOULD happen)

def test_taxonomy_service_handles_missing_parent_gracefully(self) -> None:
    """
    Regression test for AttributeError when parent taxonomy is None.

    The bug occurred when fetching a taxonomy whose parent was deleted.
    """
    # Arrange
    mock_repo = MockTaxonomyRepository()
    mock_repo.set_parent_returns_none()
    service = TaxonomyService(mock_repo)

    # Act & Assert
    # Should not raise, should return None or empty
    result = service.get_taxonomy_with_parent("orphan-id")
    assert result.parent is None

task test -- tests/path/to/test_file.py::TestClass::test_method -v

## Fix Plan

**Approach**: [How to fix it]

**Files to modify**:
- `path/to/file.py` - [What change]

**Why this fixes it**:
[Explanation connecting fix to root cause]

task test -- tests/path/to/test_file.py::TestClass::test_method -v

task test -- tests/path/to/module/

task lint
task test

## Bug Fix Complete

### Original Error
[Stack trace / error message]

### Root Cause
[Concise explanation]

### Fix
**File**: `path/to/file.py`
**Change**: [Description of the fix]

### Regression Test
**File**: `tests/path/to/test.py`
**Test**: `test_<name>`

### Verification
- Regression test passes
- Related tests pass
- Full test suite passes
- Linting passes

Bug fix complete and verified. Would you like me to open a Pull Request?

- Yes, create PR targeting main/master
- Yes, but target a different branch
- No, I'll handle the PR myself

git add -A
git commit -m "fix: <concise description of what was fixed>

Root cause: <brief explanation>
Solution: <what was changed>

Adds regression test to prevent recurrence."

git push -u origin <branch-name>

gh pr create --title "fix: <concise description>" --body "## Summary
<1-2 sentences explaining what this PR fixes>

## Problem
<What was the bug - error type, when it occurred, impact>

## Root Cause
<Why the bug happened - 1-2 sentences>

## Solution
<How it was fixed - 2-4 bullet points>

## Changes
- \`path/to/file.py\`: <what changed>
- \`tests/path/to/test.py\`: <regression test added>

## Testing
- Added regression test: \`test_<name>\`
- Verified fix with <reproduction method>
- All existing tests pass

## Notes for Reviewers
<optional - edge cases considered, alternative approaches rejected, etc.>"

PR created: <link>

Note: You're in worktree `../cernel-backend-bugfix-<desc>`.
To return to main workspace: cd ../cernel_backend
To remove worktree later: git worktree remove ../cernel-backend-bugfix-<desc>