workflows/screen-debug.md

# Workflow: screen-debug

> **Capture and analyze screen state for debugging agent behavior.**

## Prerequisites

- `screencapture` available (macOS built-in)
- `WindowManager` class available in `agent_controller.py`

## Steps

1. **Declare capture**
   - Log: `[ScreenDebug] Capturing screen for debugging at {timestamp}`
   - Purpose: "debug"
   - This satisfies Rule 00: No stealth capture

2. **Capture all windows**
   - For each window index 0-3:
     - `WindowManager.capture_window_screenshot(window_index)`
     - Save path to list

3. **Capture full screen**
   - `screencapture -x /tmp/screen_debug_{timestamp}.png`

4. **OCR each window**
   - Run `_ocr_screenshot()` on each capture
   - Log OCR quality score and first 200 chars

5. **Run vision model (if OCR quality < 30)**
   - Use `ollama.vision()` as fallback
   - Log vision model response

6. **Analyze agent state**
   - Log: which agents are alive (`thread.is_alive()`)
   - Log: last output timestamp for each agent
   - Log: message bus recent messages

7. **Write report**
   - Save analysis to `/tmp/screen_debug_{timestamp}.md`
   - Include: screenshot paths, OCR text, agent states, bus messages

8. **Write receipt**
   - Artifact: debug report
   - Use `/create-receipt` workflow