ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

ascii gui comms worflow ideation

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-06-08 20:32:42 -04:00
parent 161ebb0da6
commit d7a065e9d5
1 changed files with 341 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reports/ascii_sketch_ux_workflow_20260608.md
+341
View File
@@ -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: <click to expand>] | <- 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 | `|<n>|` or `|<n> [drag]|` | `|8|` or `|8 [drag]|` | Square-bounded, no border-by-default |
| Collapsed section | `<click to expand>` | `<click to expand>` | 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 `<scrollable region>` annotation at the top)
### What ASCII doesn't capture
- Animation (e.g. the spinner during LLM call — use `[...]` and a comment `<spinner: animated>`)
- 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 `<pop-out to viewport>`)
- Drag-and-drop (use `<drag: target>` notation)
- Tooltips on hover (use `<tooltip: text>` 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] <tooltip: Save the discussion to project TOML>`.
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.*