| 1 | <!-- English translation of adr/0003-debug-ui-mode-separate-from-power.md. Canonical Russian: ../../adr/0003-debug-ui-mode-separate-from-power.md --> |
| 2 | |
| 3 | # ADR 0003: Separate Debug UI Mode (Not the Power Cockpit) |
| 4 | |
| 5 | **Status:** Accepted (product direction); **implementation** per release plan |
| 6 | **Date:** 2026-04-02 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0001](0001-debug-hypotheses-json-storage.md) | Debug hypotheses stored in a single JSON file | |
| 13 | |
| 14 | ### Outside ADR |
| 15 | |
| 16 | | Document | Role | |
| 17 | |----------|------| |
| 18 | | [ux/cascade-ide-ui-layout-v1.md](../ui-ux/cascade-ide-ui-layout-v1.md) | Current Focus / Balanced / Power | |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## Context |
| 23 | |
| 24 | **Power** mode is overloaded with telemetry, agent trace, task queue, and the autonomous-scenario cockpit. A “**mostly debugging**” scenario (breakpoints, stack, variables, hypotheses, reproducing a bug) should not require turning on that entire layer. In that scenario the IDE is an **observer and MCP executor** (debug state, commands, UI for the agent), while **dialogue with the agent and autonomous flows** stay in **Cursor**; the built-in IDE chat does not duplicate the primary chat role. |
| 25 | |
| 26 | ## Decision |
| 27 | |
| 28 | Introduce a separate **Debug UI mode** (exact menu/registry name TBD at implementation): |
| 29 | |
| 30 | - A layout focused on debugging and related panels (including hypotheses — [ADR 0001](0001-debug-hypotheses-json-storage.md)). |
| 31 | - **Minimal chrome:** no Quick Actions, no bottom panel “terminal / build / git / …” by default; build and console for the scenario live in **Cursor** or via explicit **View** toggles, not as permanent mode chrome. |
| 32 | - Hide or strongly reduce Power-specific UI (cockpit task queue, agent telemetry where not needed for debugging). |
| 33 | - Preserve the principle from [0002](0002-debug-human-agent-parity.md): one debug state for human and MCP. |
| 34 | |
| 35 | ### Panel visibility map (target state) |
| 36 | |
| 37 | Main-window zones follow [ux/cascade-ide-ui-layout-v1.md](../ui-ux/cascade-ide-ui-layout-v1.md). The table below is not commentary — each row answers **what Debug keeps on screen** and **what Debug hides** (relative to Power and partly Balanced). Hotkeys and bindings land in the UI spec when the mode ships. |
| 38 | |
| 39 | | Zone | Shown in Debug | Hidden in Debug | |
| 40 | | --- | --- | --- | |
| 41 | | **Task cockpit** (row under toolbar) | Minimum needed to **run under the debugger** and navigate the task (without duplicating a full “work” strip) | **Quick Actions** (Balanced / `quick_actions` capability); **Autonomous** block and rest of cockpit chrome for **Power** family (`UiModeFamily.Power`) | |
| 42 | | **Solution Explorer** | Solution tree, file navigation | **PowerTaskQueueItems** queue under the tree (yes in Power, no in Debug) | |
| 43 | | **Editor column** | 1–2 editor groups; **stack/variables** panel when a DAP session is active | Third group by default (as in Power); **inline build output** under the editor — **hidden** by default (build out of mode focus); Power-only doc chrome | |
| 44 | | **Right column (chat)** | By default **no chat column**: `ChatPanelExpanded: false` in mode spec, column width **0 px** (no narrow strip), splitter before chat hidden; area goes to editor and debug panels. Restore chat via **View → Chat**, toolbar **Show chat**, or MCP | Expanded built-in chat as in Balanced/Power; **Agent Trace**; **Agent Operations**; Power chat layout. Rationale: primary chat in **Cursor**, IDE autonomy **deferred**, no need to duplicate the dialogue strip in the debug window | |
| 45 | | **Telemetry strip** | Minimum info; **debug status** is appropriate; build/tests/git optional or hidden to avoid duplicating the “everything in Cursor” scenario | Extended Power-cockpit and duplicates that exist only in Power | |
| 46 | | **Bottom panel** | By default **collapsed** or only debug-meaningful tabs: **Debug** (stack/variables in dock), plus **Hypotheses** ([0001](0001-debug-hypotheses-json-storage.md)); see below | **Terminal**, **Build output**, **Git**, **Events**, **Tests** — **not expanded** by default; available via **View** when unavoidable (repro, manual git, etc.) | |
| 47 | |
| 48 | ### Hypotheses: UI zone (decided) |
| 49 | |
| 50 | - **Right chat column** — not used for the hypothesis list (chat in Cursor; column collapsed by default in Debug). |
| 51 | - **Target:** dedicated **Hypotheses** tab in the **bottom panel**, on the same strip as **Debug** — shared debug context; expand the bottom panel via **View** when the list or stack in the dock is needed. |
| 52 | - **Fallback** (only if implementation is tight): part of the list or a duplicate next to stack/variables in the editor column; bottom-panel tab still wins. |
| 53 | |
| 54 | ### Breakpoints: UI zone, data model, agent |
| 55 | |
| 56 | - **Window zone:** a separate “breakpoint list” column is not required. Points are set in the editor **gutter** today; if a list with actions appears later, place it in the **debug** zone (bottom panel / next to stack/variables), not as a fourth main-window column. |
| 57 | - **Model:** one record in storage (`.dotnet-debug-mcp-breakpoints.json` / `BreakpointEntry`) — an **active** point; toggling in the UI removes or adds the record, **without** Visual Studio–style “disabled but line still marked”. |
| 58 | - **Product boundary:** **enabled/disabled** without removing from JSON is **intentionally out of scope** until an explicit request and a separate schema/DAP decision. If needed later — separate ADR or breakpoint-storage addendum. |
| 59 | - **Agent (Cursor / MCP):** source of truth for the list is the **on-disk file** and tools like `debug_list_breakpoints`; no push to chat. After human edits in the IDE the agent sees current state on the **next** file read or tool call, not instantly. |
| 60 | |
| 61 | ### Initial layout (mode registry) |
| 62 | |
| 63 | When added to `UiModeLayoutRegistry` (or equivalent), Debug gets its own `UiModeLayoutSpec`: **tree enabled**, **`TerminalVisible: false`**, **`BuildOutputVisible: false`**, **`ChatPanelExpanded: false`**, **editor group count** 1–2; bottom panel and inline build output under the editor off or collapsed in spec by default. Exact values are fixed in the commit that introduces the mode. |
| 64 | |
| 65 | Control map and hotkeys — update `cascade-ide-ui-layout-v1` (or successor) after the mode exists in code. |
| 66 | |
| 67 | ## Consequences |
| 68 | |
| 69 | - Requires extending `UiModeLayoutRegistry` / equivalent and conditional visibility, not only a new tab inside Power. |
| 70 | - Mode documentation updates when the mode ships in code. |
| 71 | |
| 72 | ## Rejected alternatives |
| 73 | |
| 74 | - **Power only + new tab** without a separate mode — rejected: does not isolate the “debug only” scenario. |
| 75 | - **Full window duplication** — not required; a mode in the same main window is enough. |
| 76 | |