| 1 | <!-- English translation of adr/0011-debug-situational-awareness.md. Canonical Russian: ../../adr/0011-debug-situational-awareness.md --> |
| 2 | |
| 3 | # ADR 0011: Situational Awareness in Debugging (Priority Over a “Full” Bottom Panel) |
| 4 | |
| 5 | **Status:** Accepted (direction; concrete screens and hotkeys per implementation iteration) |
| 6 | **Date:** 2026-04-02 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0002](0002-debug-human-agent-parity.md) | Single state layer | |
| 13 | | [0003](0003-debug-ui-mode-separate-from-power.md) | Debug mode | |
| 14 | | [0012](0012-floating-workspace-chrome.md) | Floating chrome — where to put strips without competing with editor height | |
| 15 | |
| 16 | ### Outside ADR |
| 17 | |
| 18 | | Document | Role | |
| 19 | |----------|------| |
| 20 | | [MCP-PROTOCOL.md](../../MCP-PROTOCOL.md) | Debug commands | |
| 21 | |
| 22 | --- |
| 23 | |
| 24 | ## Context |
| 25 | |
| 26 | While debugging, the user needs **process state** (stopped / running, where stopped, why) and **situational awareness** — without permanently expanding the bottom zone to large height. |
| 27 | |
| 28 | Fact: **increasing bottom-panel height** (output, instrumentation, debug) **inevitably eats editor vertical space**. If the only way to “understand debugging” is a full locals/stack list at the bottom, reading code suffers. The **agent** can already get stack and variables via MCP; the **human** needs UX that delivers awareness **in the line of sight** and **at the code**, without keeping the panel inflated. |
| 29 | |
| 30 | ## Decision |
| 31 | |
| 32 | <a id="adr0011-p1"></a> |
| 33 | 1. **Product priority** in the debug zone: **state and situational awareness** matter more than the habit of “always seeing the full bottom panel”. Detailed variable/stack lists remain necessary but as a **secondary**, expandable layer. |
| 34 | |
| 35 | <a id="adr0011-p2"></a> |
| 36 | 2. **Primary layer (implementation direction):** |
| 37 | - **Explicit debug state** in a persistent or near-persistent zone: *paused / running*, when possible *stop reason* (breakpoint, step, exception), brief **frame context** (at least top of stack one line: method / file:line). |
| 38 | - **Current line** in the editor (highlight, arrow) stays the mandatory anchor for “where I am in code” — without weakening [0002](0002-debug-human-agent-parity.md). |
| 39 | |
| 40 | <a id="adr0011-p3"></a> |
| 41 | 3. **Compact “debug strip”** (or equivalent: status bar / narrow zone under toolbar): **small** height vs the editor; when needed **one line** of key info (e.g. top frame + paused). Full tabbed panel — **on explicit action** (click, hotkey, “detailed” mode), not the only way to know state. |
| 42 | |
| 43 | <a id="adr0011-p4"></a> |
| 44 | 4. **In-code depth (direction):** hints with **values** on identifier hover / at caret (**VS Data Tips analog**), via DAP **`evaluate`** (or adapter equivalent) in the current frame context. Reduces reliance on the locals list in the bottom panel for typical “what’s in this variable?”. |
| 45 | |
| 46 | <a id="adr0011-p5"></a> |
| 47 | 5. **Bottom panel** is not declared harmful; it is declared **not required for baseline awareness**. Reasonable defaults: **do not auto-expand to maximum height** on stop when a strip/status exists; optional setting “show debug tab on stop” (optional, not a blocker for [§2](#adr0011-p2)–[§4](#adr0011-p4)). |
| 48 | |
| 49 | <a id="adr0011-p6"></a> |
| 50 | 6. **Parity with the agent** ([0002](0002-debug-human-agent-parity.md)): MCP text responses (`debug_stack_trace`, `debug_variables` with child expansion) remain the channel for fullness; human UX adds a **compressed persistent layer** and **inline/hover**, not a full list everywhere. |
| 51 | |
| 52 | ## Consequences |
| 53 | |
| 54 | - Separate UI work (strip/status), **evaluate on hover** (DAP + editor offset/symbol map), bottom-zone height policy — **without removing** the existing debug panel. |
| 55 | - User documentation (later): where to read state and how to open full stack/locals. |
| 56 | - Vertical splitter conflict remains an engineering constraint; this ADR **does not** require a separate output window but does not forbid it as a follow-up. |
| 57 | |
| 58 | ## Rejected alternatives (as the sole answer) |
| 59 | |
| 60 | - **Bottom panel only** as the human source of debug truth — rejected: conflicts with awareness without losing code on screen. |
| 61 | - **MCP/agent only** without UI improvement — rejected: human and agent remain equal consumers of one state layer ([0002](0002-debug-human-agent-parity.md)), but human UX must be **self-sufficient** without mandatory chat. |
| 62 | |