Bugfix Workflow

1.2 Attempt Reproduction

1. Start dev server: npm run dev
2. Navigate to affected area
3. Follow reported steps
4. Check browser console for errors
5. Check terminal for server errors

1.3 Document Findings

## Bug Report

**Expected**: [behavior]
**Actual**: [behavior]
**Steps**: 
1. [step 1]
2. [step 2]
**Environment**: [browser/device]
**Console Errors**: [errors if any]

1.4 Severity Assessment

Phase 2: Diagnose

2.1 Narrow Down Location

1. Identify affected component (grep by text/feature)
2. Check related store state
3. Check engine calculations (if music theory)
4. Check i18n keys (if translation issue)
5. Check theme/styles (if visual issue)

2.2 Common Bug Categories

State Issues

// Check if state is updating
const { currentKey, harmonyResult } = useAppStore();
console.log('currentKey:', currentKey);

// Check if action is called
setKey(root, tonality);

Symptoms: UI doesn't update, stale data
Causes: Missing state update, wrong selector, race condition

Calculation Issues

// Check engine output
import { calculateHarmony } from '@/lib/music-theory/engine';

const result = calculateHarmony('C', 'Major');
console.log('Harmony result:', result);

Symptoms: Wrong notes/chords, unexpected values
Causes: Wrong formula, edge case not handled, wrong constants

Component Issues

// Check props and rendering
const Component = ({ value }: Props) => {
  console.log('Component render:', value);
  // ...
};

Symptoms: UI glitch, wrong display, crash
Causes: Missing prop, wrong prop type, null/undefined

Styling Issues

// Check theme values
const StyledDiv = styled.div`
  background: ${({ theme }) => {
    console.log('theme:', theme);
    return theme.colors.background;
  }};
`;

Symptoms: Wrong colors, layout break, overflow
Causes: Wrong theme path, missing responsive styles, CSS specificity

2.3 Debugging Tools

2.4 Root Cause Identification

## Diagnosis Summary

**Location**: [file:line]
**Root Cause**: [description]
**Type**: [state/calculation/component/style/other]
**Affected Code**:
- [file1]
- [file2]
**Side Effects**: [other affected areas]

Phase 3: Fix

3.1 Fix Strategy

3.2 Minimal Fix Principle

DO:
- Make smallest change that fixes the bug
- Preserve existing behavior elsewhere
- Add defensive checks (null guards, edge cases)
- Follow existing code patterns

DON'T:
- Refactor surrounding code
- Add new features
- Change unrelated behavior
- Over-engineer the solution

3.3 Common Fix Patterns

Null/Undefined Guard

// Before
const name = user.profile.name;

// After
const name = user?.profile?.name ?? 'Unknown';

State Update Fix

// Before
set({ value: newValue });

// After - if depending on previous state
set((state) => ({ ...state, value: newValue }));

Edge Case Handling

// Before
const scale = scales[tonality];

// After
const scale = scales[tonality] ?? scales['Major']; // fallback
if (!scales[tonality]) {
  console.warn(`Unknown tonality: ${tonality}, using Major`);
}

Responsive Fix

// Before
const Container = styled.div`
  width: 500px;
`;

// After
const Container = styled.div`
  width: 100%;
  max-width: 500px;
  
  @media (max-width: 768px) {
    width: 100%;
    max-width: none;
  }
`;

3.4 Add Regression Test

Document the bug to prevent recurrence:

## Bug: [Title]

**Issue**: [description]
**Fix**: [what was changed]
**Files**: [list]
**Test case**: [steps that would have caught this]

Phase 4: Verify

4.1 Direct Testing

1. Reproduce original bug - should NOT occur
2. Test the fix in isolation
3. Test with edge cases
4. Test on different browsers (if relevant)
5. Test responsive behavior (if UI)

4.2 Regression Testing

1. Check related features still work
2. Check no new console errors
3. Check no TypeScript errors
4. Check no ESLint warnings

4.3 Run Validation

npm run lint
npm run build

4.4 Verification Checklist

## Bug Fix Verification

- [ ] Original bug is fixed
- [ ] No new errors introduced
- [ ] Edge cases handled
- [ ] Lint passes
- [ ] Build passes
- [ ] Related features still work

4.5 Recommend Code Review

Bug fix complete. I recommend code review:

"@SeniorCodeReviewer please review this bug fix in [file]:
- Original issue: [description]
- Root cause: [cause]
- Fix: [change made]"

Common Bug Patterns in This Project

Music Theory Engine

State Management

i18n

Styling

When to Escalate

Escalate to specialists when:

Quick Reference

# Start dev server
npm run dev

# Check for errors
npm run lint
npm run build

# Search for code
grep -r "search term" src/

# Check specific file
cat src/path/to/file.tsx