# 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.*
