manual_slop/conductor/tracks/hot_reload_python_20260510/plan.md

Implementation Plan: Hot Reload Python Codebase

Phase 1: Core File Watcher Infrastructure

Focus: File system watcher using watchgod with subprocess restart

• Task 1.1: Add watchgod dependency to pyproject.toml
• Task 1.2: Create src/hot_reload.py with HotReloadWatcher class using watchgod
• Task 1.3: Implement debounced file change handler (300ms window)
• Task 1.4: Implement subprocess restart logic with same CLI arguments
• Task 1.5: Handle graceful shutdown before restart
• Task 1.6: Write tests for HotReloadWatcher in tests/test_hot_reload.py
• Task 1.7: Write tests for subprocess restart behavior

Phase 2: CLI/Entry Point Integration

Focus: Wire hot reload into application entry points

• Task 2.1: Add --watch CLI flag to gui_2.py or pyproject.toml scripts
• Task 2.2: Add MANUAL_SLOP_WATCH=1 environment variable support
• Task 2.3: Add hot reload status indicator in GUI (optional)
• Task 2.4: Add logging when restart is triggered
• Task 2.5: Write integration tests for CLI flag behavior

Phase 3: Path Configuration

Focus: Configure watch patterns for the Manual Slop project structure

• Task 3.1: Watch src/**/*.py for application code changes
• Task 3.2: Watch scripts/**/*.py for helper script changes
• Task 3.3: Watch root *.py files (gui_2.py, etc.)
• Task 3.4: Exclude tests/**/*.py and logs/**/* from watch
• Task 3.5: Write tests for path filtering behavior

Phase 4: Verification

Focus: Full regression testing and user manual verification

• Task 4.1: Run pytest on tests/test_hot_reload.py
• Task 4.2: Manual verification - modify .py file, verify app restarts
• Task 4.3: Conductor - User Manual Verification (Protocol in workflow.md)