## CHANGES

- Added Code Style section to CLAUDE.md specifying tabs-for-indentation requirement 📏
- Added Root Cause Verification section under Debugging with historical bug patterns 🔍
- Added UI Bug Debugging Checklist to CLAUDE-PATTERNS.md (section 11) 🎨
- Documents CSS-first debugging, portal escapes, and fixed positioning pitfalls 🐛

CLAUDE-PATTERNS.md

@@ -252,3 +252,28 @@ const isRemote = !!session.sshRemoteId;
 // CORRECT
 const isRemote = !!session.sshRemoteId || !!session.sessionSshRemoteConfig?.enabled;
 ```
+
+## 11. UI Bug Debugging Checklist
+
+When debugging visual issues (tooltips clipped, elements not visible, scroll behavior):
+
+1. **CSS First:** Check parent container properties before code logic:
+   - `overflow: hidden` on ancestors (clipping issues)
+   - `z-index` stacking context conflicts
+   - `position` mismatches (fixed/absolute/relative)
+
+2. **Scroll Issues:** Use `scrollIntoView({ block: 'nearest' })` not centering
+
+3. **Portal Escape:** For overlays/tooltips that get clipped, use `createPortal(el, document.body)` to escape stacking context
+
+4. **Fixed Positioning:** Elements with `position: fixed` inside transformed parents won't position relative to viewport—check ancestor transforms
+
+**Common fixes:**
+```typescript
+// Tooltip/overlay escaping parent overflow
+import { createPortal } from 'react-dom';
+{isOpen && createPortal(<Overlay />, document.body)}
+
+// Scroll element into view without centering
+element.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+```

CLAUDE.md

@@ -64,6 +64,12 @@ Use these terms consistently in code, comments, and documentation:
 
 ---
 
+## Code Style
+
+This codebase uses **tabs for indentation**, not spaces. Always match existing file indentation when editing.
+
+---
+
 ## Project Overview
 
 Maestro is an Electron desktop app for managing multiple AI coding assistants simultaneously with a keyboard-first interface.
@@ -260,6 +266,20 @@ See [[CLAUDE-PATTERNS.md]] for detailed SSH patterns.
 
 ## Debugging
 
+### Root Cause Verification (Before Implementing Fixes)
+
+Initial hypotheses are often wrong. Before implementing any fix:
+
+1. **IPC issues:** Verify handler is registered in `src/main/index.ts` before modifying caller code
+2. **UI rendering bugs:** Check CSS properties (overflow, z-index, position) on element AND parent containers before changing component logic
+3. **State not updating:** Trace the data flow from source to consumer; check if the setter is being called vs if re-render is suppressed
+4. **Feature not working:** Verify the code path is actually being executed (add temporary `console.log`, check output, then remove)
+
+**Historical patterns that wasted time:**
+- Tab naming bug: Modal coordination was "fixed" when the actual issue was an unregistered IPC handler
+- Tooltip clipping: Attempted `overflow: visible` on element when parent container had `overflow: hidden`
+- Session validation: Fixed renderer calls when handler wasn't wired in main process
+
 ### Focus Not Working
 1. Add `tabIndex={0}` or `tabIndex={-1}`
 2. Add `outline-none` class