# Track Specification: Hot Reload Python Codebase

## Overview

Add file system watching capability to automatically reload/restart the Manual Slop application when source files are modified during development. This eliminates the manual stop/restart cycle when iterating on the codebase.

## Current State Audit (as of 4940913e)

### Already Implemented (DO NOT re-implement)

- **gui_2.py**: Main application entry with `App` class, `run()` method, and imgui-bundle integration
- **src/app_controller.py**: Application controller with state management
- **pyproject.toml**: Project configuration with `[project.scripts]` for `manual-slop` entry point
- **scripts/**: Helper scripts for various dev tasks

### Gaps to Fill (This Track's Scope)

1. **No hot reload mechanism**: No watchdog/inotify-based file watching to trigger app restart
2. **Manual restarts required**: Developers must stop and restart the app after every code change
3. **No dev iteration helper**: No integration with existing dev tooling (watchgod, hupper, or py --watch)

## Goals

1. Watch source files (*.py) in src/, scripts/, and root directories
2. Automatically restart the running application when Python files change
3. Provide a CLI flag or environment variable to enable/disable hot reload mode
4. Debounce rapid file changes to prevent restart storms
5. Preserve application state where possible during reload

## Functional Requirements

- File system watcher using `watchgod` (lightweight, pure Python, no C extensions)
- Watch patterns: `src/**/*.py`, `scripts/**/*.py`, `*.py` in project root
- Debounce window: 300ms to coalesce rapid file changes (e.g., save-all)
- CLI flag: `--watch` or `MANUAL_SLOP_WATCH=1` environment variable
- Graceful shutdown before restart, preserving logs
- Restart via subprocess with same arguments

## Non-Functional Requirements

- Must not block the main thread
- Memory overhead < 5MB
- Restart latency < 1 second after file change settles
- Compatible with Windows (PowerShell environment)

## Architecture Reference

- docs/guide_architecture.md#threading-model
- pyproject.toml#project.scripts

## Out of Scope

- Hot reload within the same process (AST-level code swapping)
- Watching non-Python files
- Cross-machine or container-based file watching
- IDE integration (VSCode, etc.)