diff --git a/docs/reports/ascii_sketch_ux_workflow_20260608.md b/docs/reports/ascii_sketch_ux_workflow_20260608.md new file mode 100644 index 00000000..e77b67a6 --- /dev/null +++ b/docs/reports/ascii_sketch_ux_workflow_20260608.md @@ -0,0 +1,341 @@ +# ASCII-Sketch UX Ideation Workflow for Manual Slop + +**Track:** TBD (not yet specced) +**Date:** 2026-06-08 +**Author:** Tier 2 Tech Lead (proposal) +**Status:** Draft for later pickup + +> **What this is.** A workflow for ideating Manual Slop GUI changes with the user, using ASCII sketches as the shared visual language. The motivation: you can't directly show me a screenshot of the GUI from inside this session, and pixel-level image-understanding tools (like `MiniMax understand_image`) are indirect. ASCII is the most direct way to share what a panel "should look like" without leaving the text medium. This document defines the workflow, the conventions, the recommended first target, and the integration with the existing track system. +> +> **What this is NOT.** This is not a proposal to replace ImGui or the existing pixel-based design tools. It's an addition — a *text-side* workflow that runs alongside the existing design and review process. + +--- + +## 0. Why ASCII for an ImGui app + +ImGui has characteristics that make ASCII a *good enough* proxy for the actual rendered GUI: + +1. **ImGui is immediate-mode and rectilinear.** Every widget is a rectangle at a known position. There's no animation, no transforms, no custom drawing that escapes the rectilinear model. ASCII box-drawing characters map directly to ImGui's positioning. + +2. **ImGui has a regular layout grammar.** Headers, buttons, separators, text inputs, combos, checkboxes, sliders — all have a canonical visual form. Once you know the grammar, the ASCII is mechanical. + +3. **Manual Slop is information-dense, not visually ornate.** The NERV theme is the most visual variation; the default theme is a standard dark ImGui. Most panels are text + buttons + tables. + +4. **ImGui is a *what* not a *how*.** The pixel positions don't matter for design — what matters is: "what widgets are present, in what order, with what labels, with what state." ASCII captures all of that. + +5. **You can sketch, critique, and revise faster than any visual tool.** For a first draft of "what should this panel be," ASCII is 10x faster than Figma/Sketch and 100x faster than 3 render passes in ImGui. + +**Where ASCII falls down:** +- Custom shaders (NERV CRT scanlines, FBO-based effects) +- Animations and transitions +- Color schemes (we'd need to add color annotations separately) +- Pixel-perfect spacing (we'd need to indicate "this should be ~half the width of the panel") +- Multi-viewport layouts (popped-out windows) + +For those cases, the workflow falls back to the `MiniMax understand_image` path with an actual screenshot. + +--- + +## 1. The workflow (5 steps) + +### Step 1: Pick a target panel + +Either you or I suggest a specific panel or feature. The panel should be: +- **Self-contained** (not a 4-window popup with sub-menus) +- **Currently-shipped or close to it** (so we can ground the sketch in reality) +- **Iterative** (we expect to refine the design before code) + +**Recommended first target:** The per-entry rendering of the Discussion Hub. Currently `src/gui_2.py:3770 render_discussion_entry` — a 100+ line function with header controls, body, Ins/Del/Branch buttons, role combo, thinking-trace handling. The full operation matrix is `guide_discussions.md` §"Per-Entry Operations" (A1-A7, 7 operations per entry). + +Other good candidates: +- The Context Panel file row (view mode picker, force_full toggle, custom_slices indicator) +- The Truncate/Compress/Save discussion panel (`gui_2.py:4239 render_discussion_entry_controls`) +- The MMA spawn-approval modal (`gui_2.py:5163+`) +- The Vendor State tab (post-Vendor-Capability-Matrix ship) +- The Persona editor modal + +### Step 2: Establish the boundary + +Before sketching, agree on: +- **What's inside the panel** (the rectangle's content) +- **What's outside** (parent panel, scroll container, menu bar) +- **What state is shown** (collapsed entry vs expanded, edit mode vs read mode, empty vs populated) +- **What interactions are in scope** (click → what happens, hover → what tooltip) +- **What color/theme is assumed** (default, NERV, etc.) + +For the Discussion Hub target, the boundary is: +- **Inside:** one entry, header + body, all 7 operations (A1-A7) +- **Outside:** the discussion selector (B6) above, the discussion-level controls (B1-B11) below +- **State:** expanded, edit mode, AI role, has thinking segments +- **Interactions:** click +/- to collapse, click [Edit]/[Read] to toggle mode, click combo to change role, click Ins/Del/Branch +- **Theme:** default (since the NERV theme is opt-in and we want a baseline first) + +### Step 3: ASCII sketch (me, then you) + +I generate a first draft ASCII sketch based on the boundary. You critique. + +**My draft of the per-entry panel** (current `gui_2.py:3770` behavior, before any changes): + +``` ++------------------------------------------------------------------+ +| [+/-] Entry #3 [Role: AI v] [Edit] @2026-06-08T12:34 | <- header +| in:120 out:340 +| in:120 out:340 | ++------------------------------------------------------------------+ +| | +| [thinking trace: ] | <- thinking +| "I think the right approach is to split the parser | body +| into two phases..." | +| | +| ---collapsed: rest of 8,200 chars--- | ++------------------------------------------------------------------+ +| [Ins] [Del] [Branch] I noticed that foo.py:42 uses an... | <- footer (when collapsed) ++------------------------------------------------------------------+ +``` + +**The convention I'm proposing:** + +``` ++--+ = fixed-width UI element (button, label, separator) +[...] = bracketed interactive control (button label, combo trigger, etc.) +[ v] = dropdown / combo (the "v" is the dropdown indicator) +[...] [v] = combo with currently-selected value +<...> = collapsible section (click to expand) +"..." = text content (truncated to ~60 chars per line) +@... = timestamp or metadata +in:N out:N = token usage (when available) +``` + +**You critique.** Your response might be: "the Ins/Del/Branch buttons should be on the *right* side, not split between collapsed and expanded; the timestamp should be in a tooltip, not inline; collapse the token usage behind a single '...' icon." Or: "this looks fine, ship it." Or: "show me the edit mode version too." + +### Step 4: Iterate + +We iterate. I revise the sketch based on your critique. We converge on a design that you would *want* to see in the GUI. + +**Iteration rules:** +- One round = one revision from me, one critique from you +- After 3 rounds, if we haven't converged, the panel is probably too complex to sketch in ASCII and we should use the image-understanding path +- Each revision is a full redraw (not a diff), so the conversation reads as a sequence of candidate designs + +### Step 5: Lock the design + +Once you say "that's it," the final ASCII sketch becomes a **design contract** for the panel. The contract has 3 parts: + +1. **The ASCII sketch itself** (the visual) +2. **A list of interactions** (click, hover, drag, keyboard) with their effects +3. **A list of states** (collapsed/expanded, edit/read, populated/empty) and the conditions that trigger them + +The contract goes into a sub-spec of the `Manual UX Validation & Review` track (or whichever track the panel is part of). The implementing Tier-3 worker reads the ASCII + interaction list + state list, and implements in ImGui to match. We verify by rendering the actual GUI and using `MiniMax understand_image` to compare the screenshot to the ASCII sketch. + +--- + +## 2. The vocabulary (10 conventions) + +To keep sketches comparable, the workflow uses a fixed vocabulary. These are *suggestions* — adjust if you prefer different characters, but be consistent. + +| Element | Symbol | Example | Notes | +|---|---|---|---| +| Button | `[Label]` | `[Save]` | Always `[...]` with no padding inside | +| Button (with state) | `[✓] Label` or `[X] Label` | `[✓] Auto-add` | Checkmark for on, X for off | +| Combo / dropdown | `[Label v]` | `[Role v]` | The `v` is the dropdown arrow | +| Combo (selected) | `[Label: Selected v]` | `[Role: AI v]` | Shows current value before `v` | +| Text input | `|text|` | `|Keep Pairs: 4|` | Pipe-bounded, shows current value | +| Drag int | `||` or `| [drag]|` | `|8|` or `|8 [drag]|` | Square-bounded, no border-by-default | +| Collapsed section | `` | `` | Angle-bounded, indicates interaction | +| Checkbox | `[ ]` or `[X]` | `[X] Show timestamps` | Empty = off, X = on | +| Separator | `---` | `---` | Just three dashes, fixed length | +| Token usage | `in:N out:N cache:N` | `in:120 out:340 cache:80` | Plain text, no decoration | +| Timestamp | `@YYYY-MM-DDTHH:MM:SS` | `@2026-06-08T12:34:56` | ISO 8601, no decoration | +| Truncated content | `...` | `...the rest of 8,200 chars...` | Always indicate what's truncated | +| Horizontal rule | `+--+--+--+` | `+------+` | Top/bottom border of a panel | +| Vertical rule | `\|` | `\|` | Single pipe; the panel border is the pipe | + +**Panel shape:** +``` ++------------------------------------+ +| content line | +| content line (multi-line ok) | ++------------------------------------+ +``` + +**Nested panels** (e.g. an entry inside a discussion panel): +``` ++------------------------------------+ +| Entry #3 (collapsed) | ++--+---------------------------------+ + | Inner content | + | Another line | + +---------------------------------+ +``` + +**Width**: try to keep panels to 70-80 chars wide so they fit in a terminal. For wider panels, indicate "this is 60% of the parent width" in a comment. + +**Color**: when color matters, use an annotation *outside* the box: +``` +[B] <-- red border (destructive action) +[D] <-- default +``` + +**State annotations**: when a control has a state, use a suffix: +``` +[Save] <-- disabled (greyed out) +[Save *] <-- has unsaved changes +``` + +--- + +## 3. Coverage: what ASCII captures and what it doesn't + +### What ASCII captures well + +- Widget inventory (what buttons, combos, inputs, separators are present) +- Widget order (top to bottom, left to right) +- Widget grouping (what's inside the same row, what spans the full width) +- Labels and current values for non-text-input controls +- Truncation and preview text (the 60-char content preview) +- State indicators (collapsed, expanded, edit, read, populated, empty) +- Inline metadata (timestamps, token usage) +- The 7 operations on the entry (A1-A7 in the nagent_review matrix) + +### What ASCII captures with effort + +- Color (annotations outside the box) +- Disabled state (suffix marker) +- Spacing/padding (use comments) +- Multi-line text content (use `|` for line continuations, or just write the full text) +- Hierarchical grouping (use nested `+--+` boxes) +- Scroll containers (use `` annotation at the top) + +### What ASCII doesn't capture + +- Animation (e.g. the spinner during LLM call — use `[...]` and a comment ``) +- Custom drawing (e.g. NERV CRT scanlines — use a `[NERV theme]` annotation) +- Pixel-perfect typography (font weight, kerning — we work at the layout level) +- The exact color of `C_LBL()` vs `C_VAL()` (annotation only) +- Pop-out window placement (use ``) +- Drag-and-drop (use `` notation) +- Tooltips on hover (use `` notation) + +**For the things it doesn't capture, the workflow falls back to:** +1. **Animation/transition:** describe in prose. "When the entry expands, the body grows downward; no animation." +2. **Custom drawing:** describe in prose. "The role-tinted background uses theme.get_role_tint(role)." +3. **Color:** color-coded comment annotations, e.g. `[Save] <- primary (C_ACCENT)`. +4. **Tooltips:** inline in the sketch, e.g. `[Save] `. +5. **Pop-out / multi-viewport:** use the literal ASCII control name in parentheses, e.g. `[Save] (opens pop-out viewer)`. + +--- + +## 4. Comparison: ASCII vs `MiniMax understand_image` + +Both are valid. The workflow uses ASCII for *design* and the image-understanding path for *verification* and *complex visual contexts*. + +| Use case | Tool | Why | +|---|---|---| +| "What should this panel look like?" | ASCII | Speed, iteration, text-native | +| "What does this panel currently look like?" | MiniMax understand_image | The panel exists; we want to ground the sketch | +| "What does this panel look like in the NERV theme?" | MiniMax understand_image | Color matters; ASCII can't show it | +| "Sketch a 3-modal flow: collapsed → expanded → edit" | ASCII (3 sketches) | Multi-state is easy in ASCII | +| "Sketch a 3-modal flow: collapsed → expanded → edit in NERV" | MiniMax understand_image (3 screenshots) | Color matters per state | +| "Redesign the Discussion Hub per-entry panel" | ASCII first, then image for final check | The workflow | +| "Debug a visual bug in the NERV shader" | MiniMax understand_image (always) | ASCII can't show shader bugs | +| "Sketch a new feature that doesn't exist" | ASCII | Nothing to compare against | +| "Sketch an existing feature for a code-review meeting" | ASCII + image | ASCII for the design, image for "this is what we have" | + +**The MiniMax understand_image path is best for:** +- Final verification (render the actual GUI, compare to the ASCII sketch) +- NERV theme work (color matters) +- Custom shader work (e.g. the NERV FBO shader) +- Complex multi-viewport layouts (where placement in space matters) +- Visual bugs that the user can see but describe only as "this looks wrong" + +--- + +## 5. Integration with the track system + +The ASCII-sketch workflow is **not a track**. It's a *tool* used by tracks. Three integration points: + +### A. Sub-spec inside `Manual UX Validation & Review` + +Add a "Design contracts" subsection to that track's spec. Each contract is a panel-level design (ASCII + interactions + states). The track's implementation phases are organized by contract. + +### B. Optional phase inside any UX-touching track + +For a track that touches a specific panel (e.g. `UI Polish (Five Issues)` touches the `Keep Pairs` widget), the track can include a "Design review" mini-phase that: +1. Produces an ASCII sketch of the current panel +2. Produces an ASCII sketch of the target panel +3. Implements to match the target sketch +4. Verifies with `MiniMax understand_image` + +### C. Pre-track ideation + +For tracks where the *design* is unclear, the workflow can run as a pre-track conversation. The output (the locked design) becomes the track's "Design contract" appendix in the spec. + +**Recommendation:** start with (A) for the `Manual UX Validation & Review` track. (B) and (C) follow naturally once the workflow is established. + +--- + +## 6. Recommended first target: the Discussion Hub per-entry panel + +The Discussion Hub is the *best* first target because: + +1. **It's the most-edited surface.** Per the nagent_review (2026-06-08), the user has 23 distinct operations on the discussion system (A1-A7 per-entry, B1-B11 discussion-level, C1-C5 undo/redo). The user has strong opinions here and the design is contested. + +2. **It has clear boundaries.** One entry = one panel. The parent discussion wraps N entries. The discussion-level controls wrap the entries. No multi-window complexity. + +3. **The current implementation is documented.** `guide_discussions.md` §"Per-Entry Operations" lists every operation with file:line citations. The nagent_review report §3 has the full A1-A7 + B1-B11 + C1-C5 matrix. The ASCII sketch is grounded in 3+ sources. + +4. **ImGui rendering is regular.** The current `gui_2.py:3770` uses standard ImGui widgets: button, combo, input_text_multiline, separator. No custom drawing. The ASCII proxy is high-fidelity. + +5. **A target design could become a real track.** If the ASCII workflow surfaces a real design improvement, it could become a "Discussion Hub Redesign" sub-track of `Manual UX Validation & Review` (or a standalone track). + +**Proposed first sketch** (current behavior, before any changes) — see §1 Step 3 above. The next move is your critique. + +--- + +## 7. Open questions for the user + +1. **Vocabulary preference.** The §2 vocabulary is a proposal. Alternatives: + - Use box-drawing characters (`┌─┐│└─┘`) for a more "ASCII art" look + - Use Markdown tables for tabular content (less compact but more readable) + - Use a hybrid (ASCII boxes for layout, tables for tabular data) + I'd lean toward the §2 vocabulary for consistency, but you may have a preference. + +2. **Comparison policy.** After we lock a design, do we want to: + - (a) Always verify with `MiniMax understand_image` (slow but accurate) + - (b) Verify only when the design uses color/custom drawing (skip for plain ImGui) + - (c) Verify only when the implementing Tier-3 reports a mismatch + I'd lean (b) — verification proportional to complexity. + +3. **Storage location.** Where should locked designs live? + - In the track's `spec.md` as an appendix + - In a separate `conductor/designs/` directory (alongside `conductor/tracks/`) + - In a new `docs/designs/` directory (alongside the per-source-file guides) + I'd lean (a) — designs are tied to their track, and the spec is the natural home. + +4. **Tooling.** The workflow is currently *manual* (you + me + ASCII in chat). Future tooling could: + - Render ASCII to a real ImGui panel scaffold (semi-automated) + - Compare ASCII to screenshot via `MiniMax understand_image` and flag deltas + - Version-control designs as diffable text files + For now, manual is fine. Tooling can be added if the workflow proves valuable. + +5. **Frequency.** Should the workflow run for: + - Every panel change (overhead: ~10 min per panel) + - Only new panels (skip existing-panel redesigns) + - Only when explicitly requested ("let's sketch X") + I'd lean (c) — opt-in, on-demand. + +--- + +## 8. References + +- **ImGui rectilinear model:** `docs/guide_gui_2.md §"The App Class"` and `docs/guide_gui_2.md §"UI Delegation Pattern"` +- **Current per-entry implementation:** `src/gui_2.py:3770 render_discussion_entry` +- **Discussion operation matrix (the source of truth for what to sketch):** `docs/guide_discussions.md §"Per-Entry Operations (the A1-A7 matrix)"` +- **Nagent_review corrections (the user's design opinions):** `conductor/tracks/nagent_review_20260608/report.md §3` and `report.md §15 Pitfalls` +- **ImGui theme conventions:** `docs/guide_themes.md` and `docs/guide_nerv_theme.md` +- **Multi-viewport for pop-out scenarios:** `docs/guide_gui_2.md §"Multi-Viewport"` +- **The 3 new guides that give the full picture of what the user is editing:** `docs/guide_discussions.md`, `docs/guide_state_lifecycle.md`, `docs/guide_context_aggregation.md` + +--- + +*End of report. Pick this up when the user is ready to do UX ideation; the workflow is documented, the vocabulary is proposed, the first target is the Discussion Hub per-entry panel.*