Iron Laws

ALWAYS use Qt's signal/slot mechanism for UI-to-logic communication — direct method calls between UI and business logic layers break the MVC separation and cause untestable coupling.
NEVER perform long-running operations on the main UI thread — blocking the Qt event loop makes the interface unresponsive and triggers OS "not responding" dialogs.
ALWAYS apply QSS stylesheets at the application level rather than per-widget — per-widget inline styles create inconsistent themes and unmaintainable styling sprawl.
NEVER use absolute pixel coordinates for widget layout — use Qt layout managers (QVBoxLayout, QHBoxLayout, QGridLayout) to ensure DPI-aware and cross-platform rendering.
ALWAYS test the UI on all target platforms before release — PyQt6 rendering, font scaling, and widget sizing differ between Windows, macOS, and Linux.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Calling business logic directly from UI slots	Couples UI to logic; makes testing impossible and breaks MVC architecture	Emit signals from UI; connect to controller/service methods via slot
Running network or file I/O on the main thread	Blocks the Qt event loop; UI freezes until operation completes	Use QThread, QRunnable, or asyncio with quamash for background operations
Hardcoding pixel sizes and positions	Breaks on high-DPI displays and different OS DPI scaling settings	Use layout managers and size policies; use `logicalDpiX()` for DPI-aware sizing
Setting styles inline on individual widgets	Creates visual inconsistency; extremely difficult to theme or maintain	Define a single QSS stylesheet at QApplication level and use object names/classes
Ignoring cross-platform rendering differences	Widget sizes, fonts, and margins differ significantly between Windows/macOS/Linux	Test on all target platforms; use platform-conditional logic where rendering diverges

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.