brain-go-brrr: Instructions file for Claude Code

CLAUDE.md - Brain-Go-Brrr Project (FIXED ARCHITECTURE)

🔥🔥🔥 CRITICAL: ARCHITECTURE RULES TO PREVENT DISASTERS 🔥🔥🔥

RULE #1: NO PARALLEL IMPLEMENTATIONS EVER

NEVER CREATE DUPLICATE CODE IN experiments/ AND src/

What Went Wrong (The Disaster):

• Created TWO PARALLEL UNIVERSES that don't communicate
• experiments/ reimplemented everything from scratch
• src/ had working components that were ignored
• Result: AUROC=0.50 (complete training failure), wasted compute, confusion

The ONLY Correct Architecture:

# experiments/train_anything.py - MUST BE THIN
from brain_go_brrr.infra.data import Dataset  # ALWAYS USE SRC
from brain_go_brrr.infra.ml_models import Model  # NEVER REIMPLEMENT
from brain_go_brrr.domain.preprocessing import preprocess  # REUSE!

# FORBIDDEN: Creating new datasets, models, preprocessing in experiments/

RULE #2: CHECK BEFORE BUILDING

1. ALWAYS search src/ for existing implementations
2. NEVER build without checking what exists
3. ALWAYS reuse components from src/
4. NEVER create "isolated" implementations

RULE #3: NORMALIZATION IS CRITICAL

• MNE outputs: 1e-5 scale (Volts)
• EEGPT expects: N(0,1) normalized
• ALWAYS normalize before model input
• NEVER trust raw sensor data

🚨 Current Architecture Status (Aug 28, 2025)

PROBLEM DISCOVERED: Parallel implementations in experiments/ and src/

• Status: BOTH FIXED with normalization
• TODO: Migrate experiments/ to use src/ components

🚨 CRITICAL WARNING: PyTorch Lightning 2.5.2 Bug

DO NOT USE PYTORCH LIGHTNING FOR TRAINING! Lightning 2.5.2 has a critical bug that causes training to hang indefinitely at:

Loading `train_dataloader` to estimate number of stepping batches

This occurs with large cached datasets (>100k samples) and CANNOT be fixed with any settings. We tried:

• deterministic=False ❌
• limit_train_batches as integer ❌
• max_steps=10000 ❌
• num_sanity_val_steps=0 ❌
• fast_dev_run=True ❌

SOLUTION: Use experiments/eegpt_linear_probe/train_tuab.py (pure PyTorch)