# Diagnostics, Tracing & Logging Standards

This document defines how GramPilot records its autonomous sessions for debugging and replay purposes.

## 1. Frame-by-Frame Session Tracing (The "Black Box")
- **Trace Directory:** During a live run, the bot continuously dumps every seen XML layout into `debug/session_traces/<timestamp>/`.
- **Sequential Reconstruction:** Every `dump_hierarchy()` call is saved as a sequential file (e.g., `00001.xml`, `00002.xml`). 
- **Purpose:** Since the bot is 100% autonomous and makes its own decisions via LLM/Qdrant, we cannot rely on stacktraces alone if navigation fails. The session traces act as a "Black Box" flight recorder. If the bot gets stuck, developers can step through the `session_traces` XML files to see exactly what the bot "saw" and why the `SituationalAwarenessEngine` or `GoalPlanner` made a specific decision.

## 2. Standardized Logging
- **Visual Log Prefixes:** Always use clear, emoji-prefixed tags in the logger to instantly identify which subsystem is acting:
  - `🧠 [SAE]`: Situational Awareness Engine (Perception & Escape Planning)
  - `🗺️ [GOAP]`: Goal-Oriented Action Planning (Intent routing)
  - `👁️ [Telepathic]`: The fast-path / structural LLM reasoning
  - `👆 [Physics]`: Swipes, clicks, and physical interactions
  - `❄️ [VRAM Cleanup]`: Resource management
- **Log Files:** Standard execution logs are saved in the `logs/` directory for long-term auditing.

## 3. Fixture Harvesting
- **Trace to Test Pipeline:** If a session trace reveals a novel UI state that the bot failed to navigate, that specific `<sequence>.xml` file from `debug/session_traces/` must be copied to `tests/fixtures/` and integrated via `scripts/sync_fixtures.py`. 
- **Never Synthesize:** You must use the raw, failed session trace to build the failing TDD test. This guarantees that the fix addresses the actual real-world DOM structure Instagram served, not a developer's assumption.
