# Track Specification: Manual UX Validation — ASCII-Sketch Workflow (manual_ux_validation_20260608)

**Status:** Active (proposed 2026-06-08)
**Initialized:** 2026-06-08
**Owner:** Tier 2 Tech Lead
**Priority:** Medium (UX improvement; not blocking any other track)
**Type:** Workflow + first-target redesign

> **Why a new track when manual_ux_validation_20260302 already exists?** The 2026-03-02 track (`conductor/tracks/manual_ux_validation_20260302/`) is a *general* UX review track: slow-mode simulation, layout iteration, animation tuning, popup behavior. It's broad and undifferentiated. This new track is **focused** — it promotes a specific workflow (the ASCII-sketch ideation flow from `docs/reports/ascii_sketch_ux_workflow_20260608.md`) to a real track with a concrete first target (the Discussion Hub per-entry panel at `gui_2.py:3770`). The two tracks complement each other: 20260302 is the broad review; 20260608 is the focused workflow. This new track can reference the older track's "Slow-Mode Observation Harness" as a prerequisite if needed.

---

## 1. Overview

This track establishes a **text-side UX ideation workflow** for Manual Slop GUI changes, using ASCII sketches as the shared visual language between the user and the conductor/agent. The motivation is asymmetry: the user can describe what they want a panel to look like, but the agent can only verify the result via `MiniMax understand_image` on a rendered screenshot — and that path is slow + indirect. ASCII is the *direct* medium: both sides can sketch, critique, and converge in 1-3 rounds, all within a text session.

The workflow is defined in `docs/reports/ascii_sketch_ux_workflow_20260608.md` (340 lines). This track's job is to:
1. **Resolve the 5 open questions** in the workflow report (vocabulary preference, comparison policy, storage location, tooling, frequency)
2. **Execute the workflow on the first target** — the per-entry rendering of the Discussion Hub at `src/gui_2.py:3770 render_discussion_entry`
3. **Lock the design contract** for the first target (ASCII sketch + interaction list + state list)
4. **Implement the design** as a real change to `src/gui_2.py:3770`, verified by rendering the actual GUI + `MiniMax understand_image` comparison
5. **Document the pattern** so the workflow can be applied to the next ~6 candidate targets

### 1.1 What this track produces

| Artifact | Purpose |
|---|---|
| `spec.md` | This file — track design and scoping. |
| `plan.md` | 4 phases, 8-12 tasks, TDD-style with 2-5 minute granularity. |
| `metadata.json` | Structured metadata + verification criteria. |
| `state.toml` | Per-task tracking + any user-corrections. |
| `designs/discussion_hub_per_entry_v1.md` | Locked design contract for the first target. |
| `src/gui_2.py:3770` (modified) | Implemented redesign per the locked design. |
| `tests/test_render_discussion_entry_*.py` (new) | TDD tests for the implementation. |

### 1.2 Non-Goals

- **Not** replacing ImGui or the existing pixel-based design tools. ASCII is an *addition* alongside the existing design process.
- **Not** applying the workflow to all ~20 GUI panels in one go. One target (Discussion Hub per-entry), one design, one implementation. The next target is a follow-up track.
- **Not** a general UX review (that's the 20260302 track). This is the *focused* track for the ASCII-sketch workflow specifically.
- **Not** changing any non-GUI code. The App/Controller separation per `docs/guide_state_lifecycle.md` keeps this track confined to `src/gui_2.py` and the render-only layer.

---

## 2. The 5 Open Questions (must be resolved before Phase 2)

Per `docs/reports/ascii_sketch_ux_workflow_20260608.md` §1.4 and §5, the workflow has 5 open questions. These are *user decisions*, not Tier-2 decisions. They need to be answered before Phase 2 (executing the workflow on the first target).

### 2.1 Q1: Vocabulary preference

The §2 vocabulary in the report proposes:
- `[I]` for button, `===>` for flow, `o==>` for conditional flow, `[B]` for begin, `[M]` for modal, `[S]` for screen, `[Q]` for queue, `[N]` for nothing, `--` for separator

Alternatives:
- **Box-drawing characters** (`┌─┐│└─┘`) — more ASCII-art look, but harder to type in some terminals
- **Markdown tables** — better for tabular data
- **Hybrid** — ASCII boxes for layout, tables for tabular content
- **The proposed vocabulary** as-is

**Default if user doesn't pick:** the proposed vocabulary (it's well-defined, copy-pasteable, works in any terminal).

### 2.2 Q2: Comparison policy (when to verify with MiniMax understand_image)

- **Always** — every locked design gets a screenshot comparison. Slow but thorough.
- **Proportional** — only when the design uses color or non-ASCII content. Otherwise trust the ASCII.
- **Only on mismatch** — implementing Tier-3 reports a mismatch; only then verify. Fast but can miss visual bugs.
- **Never** — trust the implementation. Fastest, but the workflow's main verification step is missing.

**Default if user doesn't pick:** only-on-mismatch (the implementing Tier-3 reports success or flags deltas; conductor decides whether to verify).

### 2.3 Q3: Storage location (where the locked designs live)

- **Track's `spec.md` as an appendix** — keeps designs co-located with the track that produced them
- **`conductor/designs/`** — central location, designs persist beyond their track's lifetime
- **`docs/designs/`** — public-designs location, visible in the docs tree
- **Inline in the conductor/agent session** — the sketch lives in the conversation only

**Default if user doesn't pick:** track's `spec.md` as an appendix (co-located is simplest; can be promoted later).

### 2.4 Q4: Tooling (automation)

- **Manual** — the workflow is purely text; no tooling
- **Scaffold renderer** — a Python script that turns ASCII into a real ImGui panel scaffold (rough first pass)
- **ASCII-vs-screenshot diff** — an automated `MiniMax understand_image` call that compares the locked ASCII to a rendered screenshot
- **Diffable text designs** — design files are version-controlled; conductor diffs previous vs current

**Default if user doesn't pick:** manual (no tooling for v1; revisit if the workflow gets used 3+ times and the manual steps become rote).

### 2.5 Q5: Frequency (when to use the workflow)

- **Every panel change** — overhead ~10 min per change, maximum design rigor
- **Only new panels** — no overhead for existing panels, but no redesign opportunity
- **Only on request** — user explicitly says "use the workflow on X"
- **On track boundary** — every new track that touches `gui_2.py` triggers a workflow round

**Default if user doesn't pick:** only-on-request (the user decides when the workflow earns its overhead).

---

## 2.6 SSDL cross-reference: a different vocabulary for a different purpose

**Important distinction.** The ASCII-sketch workflow report (`docs/reports/ascii_sketch_ux_workflow_20260608.md`) uses a **GUI ASCII vocabulary** — for sketching ImGui panels (buttons, combos, separators, layouts). The SSDL digest (`docs/reports/computational_shapes_ssdl_digest_20260608.md`) uses a **computational shapes vocabulary** — for sketching data flow, control flow, and parallelism in code (codepaths, codecycles, branches, merges, nil sentinels, generational handles).

**They are two different vocabularies for two different purposes.** Conflating them is a likely failure mode:
- The GUI ASCII vocabulary (the workflow's) is about *what the user sees* (panel layout, widget inventory, state, interactions)
- The SSDL vocabulary is about *what the code does* (effective codepaths, defusing techniques, data flow)

**When to use which:**
- **GUI ASCII** for designing the panel (Phase 2 deliverable: `designs/discussion_hub_per_entry_v1.md`)
- **SSDL** for designing the panel's *internal logic* — the Python code that backs the panel. If the redesign simplifies the per-entry panel by pushing branches into subsystems (per the SSDL digest's §6 "meta-skill"), the SSDL is the right sketch vocabulary for that.

**Concrete example for the first target:** the current `gui_2.py:3770` has an `entry.get("collapsed", False)` check that runs every render frame. This is a branch in user code. Per the SSDL digest's §2.2 "Technique 1: Nil sentinel", a `[N]` defusing approach would push this branch into a subsystem: `entry_view = entry_view_for(entry)` (always returns a valid view, with the collapsed state baked in). The user's render code is then a single straight-line codepath. The SSDL sketch for this internal change looks different from the GUI ASCII sketch for the visible panel.

**Both vocabularies are useful for this track.** Phase 2 produces the GUI ASCII (the design contract for the implementing Tier-3); Phase 3 may produce SSDL sketches as documentation of the internal refactoring decisions.

---

## 3. The First Target: Discussion Hub Per-Entry Panel

### 3.1 Why this target

The per-entry rendering of the Discussion Hub is the **highest-value redesign candidate** because:

1. **It is the user-facing surface that gets interacted with most.** Every AI message and every user message is rendered through this panel. The user looks at it on every turn.
2. **The user has strong opinions here.** Per the nagent_review track (commit `9cc51ca9`), the user flagged the editable-discussion verdict (PARITY / DIFFERENT FOCUS) and the 3 rounds of corrections indicate the user thinks carefully about this surface.
3. **The 23-op matrix is the source of truth.** `docs/guide_discussions.md` enumerates the full A1-A7 (per-entry) + B1-B11 (discussion-level) + C1-C5 (undo/redo) operation matrix. The current `gui_2.py:3770 render_discussion_entry` implements a subset. The redesign should explicitly cover the full A1-A7 matrix.
4. **ImGui layout maps cleanly to ASCII.** Per-entry is a 1-column layout with header + body + footer. Standard ImGui grammar; ASCII captures it well.
5. **The current implementation is 100+ lines and has accreted state.** Refactoring it benefits from a design contract (not just "preserve existing behavior").
6. **The SSDL digest's "domain vs systems" lens (§3) and defusing techniques (§2.2) can guide the internal refactoring.** The current `gui_2.py:3770` has 4-5 branches (collapsed, read_mode, role change, ins/del, branch) that all do roughly the same thing with different inputs — exactly the pattern the SSDL digest flags as a "wide codepath" / "effective codepath" candidate. The redesign can either preserve all 4-5 branches *as visible UI affordances* (a 1-N mapping that's correct for UX) OR defuse 1-2 of them (e.g., collapse `collapsed` and `read_mode` into a single `view_state` enum). The user decides.

### 3.2 The boundary for the first target

- **Inside:** one entry, header controls + body + footer, all 7 A-operations (A1 collapse, A2 edit/read toggle, A3 role change, A4 insert before, A5 insert after, A6 delete, A7 branch)
- **Outside:** the discussion selector (B6) above; the discussion-level controls (B1-B11) below; the per-entry thinking-trace widget (separate, already in its own render function)
- **State:** expanded, edit mode, AI role, has thinking segments, has timestamp + token usage
- **Interactions:** click +/- to collapse, click [Edit]/[Read] to toggle mode, click combo to change role, click Ins/Del/Branch buttons
- **Theme:** default (NERV is opt-in; baseline first)

### 3.3 The expected ASCII sketch (first draft, for the user's critique)

See `plan.md` Phase 2 Task 2.3 for the first draft. The user will critique; we converge in 1-3 rounds.

### 3.4 The design contract (after lock)

Once the user says "that's it," the locked design is captured in `conductor/tracks/manual_ux_validation_20260608/designs/discussion_hub_per_entry_v1.md` with 3 parts:
1. **The ASCII sketch** (the visual)
2. **The interaction list** (click/hover/drag/keyboard → effect)
3. **The state list** (collapsed/expanded, edit/read, populated/empty, conditions that trigger them)

This becomes the implementation contract for `src/gui_2.py:3770`.

---

## 4. The 4 Phases (overview)

| Phase | Name | Deliverable |
|---|---|---|
| 1 | Resolve the 5 Open Questions | `decisions.md` capturing the user's choices |
| 2 | Execute Workflow on First Target | `designs/discussion_hub_per_entry_v1.md` (locked design contract) |
| 3 | Implement the Design | `src/gui_2.py:3770` modified per the contract; TDD tests pass |
| 4 | Document the Pattern | Update `docs/reports/ascii_sketch_ux_workflow_20260608.md` with the answered Q1-Q5; add 5-7 next-target candidates to a `next_targets.md` |

The full plan with 2-5 minute TDD steps is in `plan.md`.

---

## 5. Architectural Reference

- **ASCII-sketch workflow report:** `docs/reports/ascii_sketch_ux_workflow_20260608.md` (340 lines; the workflow's design + 5 open questions)
- **SSDL digest (computational shapes vocabulary):** `docs/reports/computational_shapes_ssdl_digest_20260608.md` (504 lines; 6 primitives + 7 modifiers + 5 defusing techniques + "domain vs systems" lens; a different vocabulary for the *internal logic* of the redesigned panel — see §2.6 for the GUI-ASCII vs SSDL distinction)
- **Discussion system source of truth:** `docs/guide_discussions.md` (353 lines; 23-op matrix A1-A7 + B1-B11 + C1-C5)
- **Discussion system state lifecycle:** `docs/guide_state_lifecycle.md` (375 lines; UISnapshot + HistoryManager + 4-thread access pattern)
- **GUI App class + hot-reload:** `docs/guide_gui_2.md` (477 lines; module-level render functions for state-preserving hot-reload)
- **Current implementation:** `src/gui_2.py:3770 render_discussion_entry` (100+ lines; the file to be modified)
- **Existing UX review track (complementary):** `conductor/tracks/manual_ux_validation_20260302/` (general UX review; slow-mode sim + layout iteration + animation tuning + popup behavior)

### 5.1 What this track inherits from manual_ux_validation_20260302

- The "Slow-Mode Observation Harness" (`simulation/ux_observation_sim.py`) is a useful *verification* tool: after implementing the design, run the slow-mode sim to watch the redesigned entry panel in action
- The "Auto-Close Popups" idea is a related UX concern; if the redesigned entry panel introduces new popups, those should be subject to the 20260302 auto-close policy
- The "Layout Finalization" work in 20260302 is a precedent: the user has approved the practice of "rapidly apply changes requested by the user and re-render"

### 5.2 What this track does NOT do from manual_ux_validation_20260302

- The general layout/structure iteration (Tabs vs Panels vs Collapsing Headers) is the 20260302 track's domain
- Animation tuning (blinking frequencies, color vectors) is the 20260302 track's domain
- This track is *focused* on the ASCII-sketch workflow + first target; the 20260302 track is the broad review

---

## 6. See Also

### Internal Documentation

- `docs/Readme.md` — Manual Slop documentation index
- `docs/reports/ascii_sketch_ux_workflow_20260608.md` — the workflow this track promotes (GUI ASCII vocabulary)
- `docs/reports/computational_shapes_ssdl_digest_20260608.md` — the SSDL digest (computational shapes vocabulary; for internal refactoring decisions in Phase 3, see §2.6 of this spec)
- `docs/guide_discussions.md` — the Discussion system's 23-op matrix (the source of truth for the first target)
- `docs/guide_state_lifecycle.md` — UISnapshot + HistoryManager (the state the per-entry panel preserves)
- `docs/guide_gui_2.md` — module-level render functions, hot-reload, defer-not-catch
- `docs/reports/nagent_review_20260608.md` — the nagent_review track's 3 rounds of user-corrections on the discussion system (informs what the user cares about)

### Related Tracks

- `manual_ux_validation_20260302` — the complementary general UX review track
- `nagent_review_20260608` — the source of the user's "editable discussions" corrections that this track builds on
- `chunkification_optimization_20260608_PLACEHOLDER` — the contingency track for C11 chunk-arrays (referenced in the SSDL digest's §5.2 "Xar-style chunked arrays" recommendation; the SSDL digest pre-supports the chunkification pattern)

### Related Source Material (read by the workflow author)

- `docs/transcripts/wo84LFzx5nI_big_oops_casemuratori.txt` — Casey Muratori's BSC 2025 "The Big OOPs" talk (transcript; the 35-year OOP indictment)
- `docs/transcripts/i-h95QIGchY_assuming_as_much_as_possible_andrewreece.txt` — Andrew Reece's BSC 2025 "Assuming as Much as Possible" talk (transcript; the Xar pattern)
- `data_oriented_error_handling_20260606` — the upcoming Result[T] convention (NOT directly relevant to this track, but the disc_entries list shape is a candidate for the type-alias work in `data_structure_strengthening_20260606`)

### External

- Mike Acton, "Data-Oriented Design and C++" — the philosophical foundation (via nagent_review)
- Casey Muratori, "Big OOPs" (BSC 2025, transcript at `docs/transcripts/wo84LFzx5nI_big_oops_casemuratori.txt`) — the GUI is immediate-mode + rectilinear; ASCII captures it well

---

## 7. Scope Boundaries

### In Scope

- Resolve the 5 open questions (Phase 1)
- Lock a design contract for the Discussion Hub per-entry panel (Phase 2)
- Implement the design in `src/gui_2.py:3770` (Phase 3)
- Add TDD tests (Phase 3)
- Document the pattern; propose the next 5-7 targets (Phase 4)

### Out of Scope

- Applying the workflow to all GUI panels (that's a follow-up track per panel)
- Changing the underlying Discussion data model (that's `data_structure_strengthening_20260606` + the public_api_migration_20260606 follow-up)
- Changing the per-entry thinking-trace widget (separate render function; not in scope for the first target)
- Animation tuning (general UX review; 20260302 track)
- Popup auto-close (general UX review; 20260302 track)

### Known Trade-offs (called out in the workflow report)

- **ASCII is a proxy, not a substitute.** Some ImGui features (custom shaders, NERV CRT effects, multi-viewport layouts) don't translate. The workflow falls back to `MiniMax understand_image` for those cases.
- **The workflow is not faster than just editing `gui_2.py` directly.** It adds ~10 min overhead per panel. The value is *design rigor* (the user can critique the sketch before code is written), not speed. The user decides when the overhead is worth it (Q5).
- **The first target may not be the highest-value redesign candidate.** It's a *good* candidate (high interaction, user has opinions, source of truth is documented), but the user may prefer a different first target. The 7 candidates in `docs/reports/ascii_sketch_ux_workflow_20260608.md` §1 are all valid alternatives.

---

## 8. Verification Criteria

- [ ] `metadata.json` exists with priority=medium, status=active
- [ ] `plan.md` exists with 4 phases, 8-12 tasks, TDD-style
- [ ] `state.toml` exists with task tracking
- [ ] `decisions.md` (Phase 1 deliverable) exists with the user's 5 answers
- [ ] `designs/discussion_hub_per_entry_v1.md` (Phase 2 deliverable) exists with ASCII + interactions + states
- [ ] `src/gui_2.py:3770` is modified to match the locked design
- [ ] `tests/test_render_discussion_entry_*.py` exists with the A1-A7 operations as TDD assertions
- [ ] Verification: render the actual GUI; `MiniMax understand_image` compares screenshot to the locked ASCII; deltas are reported
- [ ] `docs/reports/ascii_sketch_ux_workflow_20260608.md` is updated with the answered Q1-Q5
- [ ] `conductor/tracks/manual_ux_validation_20260608/next_targets.md` exists with 5-7 candidate panels for future workflow rounds
- [ ] (Per the docs Refresh Protocol in `conductor/workflow.md`): any docs that reference the workflow are updated

---

## 9. Status

**Proposed 2026-06-08.** Ready for Phase 1 (resolve the 5 open questions with the user).

After Phase 1: the workflow is concrete; Phase 2 (lock the first design) is executable.
After Phase 3: the first target is shipped; the workflow is validated end-to-end.
After Phase 4: the pattern is documented; the next 5-7 targets are queued for follow-up tracks.
