From 17fed4f23235dcc3a0b349fafaa854cd56038174 Mon Sep 17 00:00:00 2001
From: Pedram Amini <pedram.amini@gmail.com>
Date: Tue, 3 Feb 2026 23:29:48 -0600
Subject: [PATCH] =?UTF-8?q?##=20CHANGES=20-=20Added=20Code=20Style=20secti?=
 =?UTF-8?q?on=20to=20CLAUDE.md=20specifying=20tabs-for-indentation=20requi?=
 =?UTF-8?q?rement=20=F0=9F=93=8F=20-=20Added=20Root=20Cause=20Verification?=
 =?UTF-8?q?=20section=20under=20Debugging=20with=20historical=20bug=20patt?=
 =?UTF-8?q?erns=20=F0=9F=94=8D=20-=20Added=20UI=20Bug=20Debugging=20Checkl?=
 =?UTF-8?q?ist=20to=20CLAUDE-PATTERNS.md=20(section=2011)=20=F0=9F=8E=A8?=
 =?UTF-8?q?=20-=20Documents=20CSS-first=20debugging,=20portal=20escapes,?=
 =?UTF-8?q?=20and=20fixed=20positioning=20pitfalls=20=F0=9F=90=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE-PATTERNS.md | 25 +++++++++++++++++++++++++
 CLAUDE.md          | 20 ++++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/CLAUDE-PATTERNS.md b/CLAUDE-PATTERNS.md
index 986963ae..a9ec4f5c 100644
--- a/CLAUDE-PATTERNS.md
+++ b/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' });
+```
diff --git a/CLAUDE.md b/CLAUDE.md
index 893c28f6..f5375c7b 100644
--- a/CLAUDE.md
+++ b/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