conductor(track): manual_ux_validation_20260608_PLACEHOLDER - ASCII-sketch workflow + first-target redesign
The user said (verbatim): "On number 1. I love the idea and definitely
see poitental." This commit creates a full track that promotes the
ASCII-sketch UX ideation workflow
(docs/reports/ascii_sketch_ux_workflow_20260608.md, 340 lines) to
a real track with a concrete first target.
The track complements (does not replace) the existing
manual_ux_validation_20260302 track (which is a general UX review
track; this 2026-06-08 track is *focused* on the ASCII-sketch
workflow specifically).
Files (5 total, ~52KB, 12,000+ words):
- spec.md (186 lines, 9 sections) - track design, 5 open
questions, first target analysis, SSDL cross-reference
- plan.md (~280 lines, 4 phases, 21 tasks) - TDD-style with
WHERE/WHAT/HOW/SAFETY annotations
- metadata.json (~120 lines) - structured metadata, 5 open
questions with defaults, 5 SSDL principles available
- state.toml (~95 lines) - per-task tracking + phase status
- index.md (~50 lines) - track context + related docs
Key design decisions captured:
1. Two distinct vocabularies are conflated at first glance:
- GUI ASCII (the workflow) for panel sketches
- SSDL (computational shapes digest) for internal code sketches
Spec §2.6 makes the distinction explicit; both are useful for
this track (GUI ASCII for Phase 2 design; SSDL for Phase 3
internal refactoring documentation).
2. The 5 open questions from the workflow report (Q1 vocabulary,
Q2 comparison policy, Q3 storage location, Q4 tooling,
Q5 frequency) are documented with sensible defaults in
spec.md §2.1-2.5 and metadata.json. The user can override
any of them; defaults pre-stage the work.
3. First target is src/gui_2.py:3770 render_discussion_entry
(Discussion Hub per-entry panel). Rationale:
- Most-edited surface (every AI/user message)
- User has strong opinions (per nagent_review_20260608 3 rounds
of corrections)
- 23-op matrix A1-A7 is the source of truth
- ImGui layout maps cleanly to ASCII
- SSDL defusing techniques can guide the internal refactoring
4. 4 phases: 1=resolve 5 questions, 2=execute workflow on first
target (1-3 ASCII rounds), 3=implement per design contract
(TDD with 7 test files for A1-A7 operations),
4=document the pattern + propose 5-7 next targets.
Cross-references added throughout:
- docs/reports/computational_shapes_ssdl_digest_20260608.md
(the SSDL digest, with explicit "this is a different vocabulary
for a different purpose" note in spec §2.6)
- docs/reports/ascii_sketch_ux_workflow_20260608.md (the workflow)
- docs/guide_discussions.md (the 23-op matrix A1-A7)
- conductor/tracks/nagent_review_20260608/ (the source of the
user's editable-discussion corrections)
- conductor/tracks/manual_ux_validation_20260302/ (complementary
general UX review track)
- conductor/tracks/chunkification_optimization_20260608_PLACEHOLDER/
(the contingency track; referenced in spec §2.6 SSDL cross-ref)
No code modified. Track is active; Phase 1 (5 user-questions) is
the current phase. User-confirmed worth doing in the prior turn.
This commit is contained in:
conductor-tier2
@@ -0,0 +1,34 @@
|
||||
# Track manual_ux_validation_20260608_PLACEHOLDER Context
|
||||
|
||||
**Status:** Active (proposed 2026-06-08; awaiting Phase 1 user-answers)
|
||||
|
||||
- [Specification](./spec.md) — track design + 5 open questions + first target analysis
|
||||
- [Implementation Plan](./plan.md) — 4 phases, 21 tasks, TDD-style
|
||||
- [Metadata](./metadata.json) — structured metadata + verification criteria
|
||||
- [State](./state.toml) — per-task tracking + phase status
|
||||
|
||||
## Phase Deliverables (to be created as the track progresses)
|
||||
|
||||
- [ ] **Phase 1**: [decisions.md](./decisions.md) — the user's 5 answers to the workflow's open questions
|
||||
- [ ] **Phase 2**: [designs/discussion_hub_per_entry_v1.md](./designs/discussion_hub_per_entry_v1.md) — the locked design contract
|
||||
- [ ] **Phase 3**: `src/gui_2.py:3770` (modified) + `tests/test_render_discussion_entry_*.py` (7 new files)
|
||||
- [ ] **Phase 4**: [next_targets.md](./next_targets.md) — 5-7 candidate panels for future workflow rounds
|
||||
|
||||
## Key Design Documents (read in full before Phase 1)
|
||||
|
||||
- [ASCII-Sketch UX Workflow](../../../../docs/reports/ascii_sketch_ux_workflow_20260608.md) — 340 lines; the workflow this track promotes
|
||||
- [SSDL Digest](../../../../docs/reports/computational_shapes_ssdl_digest_20260608.md) — 504 lines; a different vocabulary for the *internal logic* of the redesigned panel (see spec §2.6 for the GUI-ASCII vs SSDL distinction)
|
||||
- [Discussion System Source of Truth](../../../../docs/guide_discussions.md) — 353 lines; the 23-op matrix A1-A7 + B1-B11 + C1-C5 that the design contract must cover
|
||||
|
||||
## First Target
|
||||
|
||||
**`src/gui_2.py:3770 render_discussion_entry`** — the per-entry rendering of the Discussion Hub. 100+ lines, currently-shipped, accreted state, user has strong opinions (per nagent_review_20260608 3 rounds of corrections).
|
||||
|
||||
## Complementary Track
|
||||
|
||||
- [manual_ux_validation_20260302](../manual_ux_validation_20260302/) — the general UX review track (broad; layout/animations/popups). This 2026-06-08 track is *focused* (the ASCII-sketch workflow + first target).
|
||||
|
||||
## Related Tracks
|
||||
|
||||
- [nagent_review_20260608](../nagent_review_20260608/) — the source of the user's "editable discussions" corrections that this track builds on
|
||||
- [chunkification_optimization_20260608_PLACEHOLDER](../chunkification_optimization_20260608_PLACEHOLDER/) — the C11 contingency track (referenced in spec §2.6 SSDL cross-reference)
|
||||
@@ -0,0 +1,104 @@
|
||||
{
|
||||
"track_id": "manual_ux_validation_20260608_PLACEHOLDER",
|
||||
"name": "Manual UX Validation — ASCII-Sketch Workflow",
|
||||
"initialized": "2026-06-08",
|
||||
"owner": "tier2-tech-lead",
|
||||
"priority": "medium",
|
||||
"status": "active (proposed 2026-06-08; awaiting Phase 1 user-answers)",
|
||||
"type": "workflow + first-target redesign",
|
||||
"scope": {
|
||||
"new_files": [
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/spec.md",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/plan.md",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/metadata.json",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/state.toml",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/index.md",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/decisions.md (Phase 1)",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/designs/discussion_hub_per_entry_v1.md (Phase 2)",
|
||||
"conductor/tracks/manual_ux_validation_20260608_PLACEHOLDER/next_targets.md (Phase 4)",
|
||||
"tests/test_render_discussion_entry_*.py (Phase 3, ~7 files for A1-A7)"
|
||||
],
|
||||
"modified_files": [
|
||||
"src/gui_2.py:3770 render_discussion_entry (Phase 3 redesign)",
|
||||
"docs/reports/ascii_sketch_ux_workflow_20260608.md (Phase 4 docs refresh)",
|
||||
"conductor/tracks.md (Phase 4 status update)"
|
||||
],
|
||||
"external_resources": [
|
||||
"ASCII-sketch workflow report: docs/reports/ascii_sketch_ux_workflow_20260608.md (340 lines; the workflow this track promotes)",
|
||||
"SSDL digest: docs/reports/computational_shapes_ssdl_digest_20260608.md (504 lines; the theoretical foundation for the internal refactoring decisions in Phase 3, per spec §2.6)"
|
||||
]
|
||||
},
|
||||
"blocked_by": [],
|
||||
"blocks": [
|
||||
"discussion_hub_redesign_20260608_PLACEHOLDER (potential follow-up; promoted from next_targets.md after Phase 4)",
|
||||
"context_panel_redesign_20260608_PLACEHOLDER (potential follow-up)",
|
||||
"mma_spawn_modal_redesign_20260608_PLACEHOLDER (potential follow-up)"
|
||||
],
|
||||
"estimated_phases": 4,
|
||||
"spec": "spec.md",
|
||||
"plan": "plan.md",
|
||||
"first_target": {
|
||||
"name": "Discussion Hub per-entry panel",
|
||||
"file_line": "src/gui_2.py:3770 render_discussion_entry",
|
||||
"operation_matrix": "docs/guide_discussions.md §Per-Entry Operations (A1-A7)",
|
||||
"rationale": "Most-edited surface; user has strong opinions (per nagent_review_20260608 3 rounds of user-corrections); 23-op matrix is the source of truth; ImGui layout maps cleanly to ASCII; SSDL defusing techniques can guide the internal refactoring"
|
||||
},
|
||||
"open_questions": [
|
||||
"Q1: Vocabulary preference (GUI ASCII vs box-drawing vs Markdown tables vs hybrid)",
|
||||
"Q2: Comparison policy (always vs proportional vs only-on-mismatch vs never)",
|
||||
"Q3: Storage location (track spec appendix vs conductor/designs/ vs docs/designs/ vs inline)",
|
||||
"Q4: Tooling (manual vs scaffold-renderer vs ASCII-vs-screenshot diff vs diffable text designs)",
|
||||
"Q5: Frequency (every change vs only new panels vs only on request vs on track boundary)"
|
||||
],
|
||||
"open_questions_defaults": {
|
||||
"Q1": "the proposed GUI ASCII vocabulary (well-defined, copy-pasteable, works in any terminal)",
|
||||
"Q2": "only-on-mismatch (Tier-3 reports success or flags deltas; conductor decides whether to verify with MiniMax understand_image)",
|
||||
"Q3": "track's spec.md as an appendix (co-located is simplest; can be promoted later)",
|
||||
"Q4": "manual (no tooling for v1; revisit if the workflow gets used 3+ times and the manual steps become rote)",
|
||||
"Q5": "only-on-request (the user decides when the workflow earns its overhead)"
|
||||
},
|
||||
"ssdl_cross_reference": {
|
||||
"distinction": "GUI ASCII vocabulary (this workflow) is for panel sketches. SSDL vocabulary (computational shapes digest) is for code sketches. They are different vocabularies for different purposes; see spec §2.6 for the full distinction.",
|
||||
"use_cases": [
|
||||
"Phase 2 (design): use GUI ASCII for the visible panel",
|
||||
"Phase 3 (implementation): may produce SSDL sketches as documentation of internal refactoring decisions (e.g., when pushing a branch into a subsystem per the SSDL 'effective codepath' pattern)"
|
||||
]
|
||||
},
|
||||
"verification_criteria": [
|
||||
"spec.md exists with §1-§9 (9 sections)",
|
||||
"plan.md exists with 4 phases and 21 tasks (TDD-style with WHERE/WHAT/HOW/SAFETY annotations)",
|
||||
"metadata.json exists with priority=medium, status=active, blocked_by=[], blocks=[3 follow-ups], 5 open questions + 5 defaults documented",
|
||||
"state.toml exists with phase tracking and task statuses",
|
||||
"Phase 1 deliverable: decisions.md exists with 5 answered questions",
|
||||
"Phase 2 deliverable: designs/discussion_hub_per_entry_v1.md exists with ASCII + interactions + states",
|
||||
"Phase 3 deliverable: src/gui_2.py:3770 modified to match the locked design",
|
||||
"Phase 3 deliverable: tests/test_render_discussion_entry_*.py exists with 7 test files (one per A-op) — all pass",
|
||||
"Phase 3 deliverable: MiniMax understand_image verification (if Q2 = always or proportional or on-mismatch) — deltas reported and either fixed or recorded in decisions.md",
|
||||
"Phase 4 deliverable: docs/reports/ascii_sketch_ux_workflow_20260608.md updated with the answered Q1-Q5",
|
||||
"Phase 4 deliverable: next_targets.md exists with 5-7 candidate panels for future workflow rounds",
|
||||
"Phase 4 deliverable: conductor/tracks.md updated to reflect track status",
|
||||
"All commits are atomic per-task (per conductor/workflow.md)",
|
||||
"All commits have git notes attached (per conductor/workflow.md)",
|
||||
"All Phase transitions have a Conductor - User Manual Verification checkpoint",
|
||||
"No code outside src/gui_2.py is modified (track is GUI-only)",
|
||||
"The 23-op matrix in docs/guide_discussions.md is the source of truth for the design contract",
|
||||
"The SSDL cross-reference in spec §2.6 is correct (GUI ASCII != SSDL; both are useful)"
|
||||
],
|
||||
"links": {
|
||||
"report": "docs/reports/ascii_sketch_ux_workflow_20260608.md",
|
||||
"comparison_table": null,
|
||||
"decisions": "conductor/tracks/manual_ux_validation_20260608/decisions.md (Phase 1)",
|
||||
"design_contract": "conductor/tracks/manual_ux_validation_20260608/designs/discussion_hub_per_entry_v1.md (Phase 2)",
|
||||
"next_targets": "conductor/tracks/manual_ux_validation_20260608/next_targets.md (Phase 4)",
|
||||
"related_tracks": [
|
||||
"manual_ux_validation_20260302 (complementary general UX review track)",
|
||||
"nagent_review_20260608 (source of the user's editable-discussion corrections)",
|
||||
"chunkification_optimization_20260608_PLACEHOLDER (contingency track; referenced in spec §2.6 SSDL cross-reference)"
|
||||
],
|
||||
"external": [
|
||||
"Ryan Fleury SSDL digest: docs/reports/computational_shapes_ssdl_digest_20260608.md",
|
||||
"Casey Muratori Big OOPs transcript: docs/transcripts/wo84LFzx5nI_big_oops_casemuratori.txt",
|
||||
"Andrew Reece Assuming as Much as Possible transcript: docs/transcripts/i-h95QIGchY_assuming_as_much_as_possible_andrewreece.txt"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,189 @@
|
||||
# Implementation Plan: Manual UX Validation — ASCII-Sketch Workflow (manual_ux_validation_20260608)
|
||||
|
||||
> **Test debt note (per the prior track pattern):** This track is **inherently visual + interactive** and is partly manual. The implementation phase (Phase 3) is TDD-friendly — `gui_2.py:3770 render_discussion_entry` has TDD-testable behavior (A1-A7 operations). The design phase (Phase 2) is not TDD — it's ASCII-sketch iteration with the user. The workflow definition phase (Phase 1) is *asking the user 5 questions* — not TDD either.
|
||||
>
|
||||
> **The phases are NOT equal-effort.** Phase 1 is ~5 min (5 questions). Phase 2 is ~30-60 min (1-3 ASCII-sketch rounds with the user). Phase 3 is the bulk: 1-3 hours of TDD implementation. Phase 4 is ~15 min (docs + next-targets).
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Resolve the 5 Open Questions (~5 min)
|
||||
|
||||
Focus: get the user's answers to the workflow's 5 open questions (per `docs/reports/ascii_sketch_ux_workflow_20260608.md` §7). Without these answers, Phase 2 cannot start (we don't know which vocabulary, which comparison policy, etc.).
|
||||
|
||||
- [ ] **Task 1.1**: Initialize MMA Environment `activate_skill mma-orchestrator`
|
||||
- [ ] **Task 1.2**: Pose the 5 open questions to the user (one at a time, with the proposed defaults in `spec.md` §2.1-2.5)
|
||||
- **WHERE**: this conversation (Tier-1 → user → Tier-1 round-trip)
|
||||
- **WHAT**: 5 questions about vocabulary, comparison policy, storage, tooling, frequency
|
||||
- **HOW**: one question per turn; multiple-choice where possible; the spec's defaults are pre-staged so the user can just say "use defaults" for all 5
|
||||
- **SAFETY**: don't lock in a default without explicit user approval. Even if the user says "use defaults," record the choice in the decision log.
|
||||
- [ ] **Task 1.3**: Write `decisions.md` capturing the 5 answers
|
||||
- **WHERE**: `conductor/tracks/manual_ux_validation_20260608/decisions.md`
|
||||
- **WHAT**: 5 sections (Q1-Q5) with the user's answer, the rationale, and any caveats
|
||||
- **HOW**: section per question; quote the user verbatim where the answer is non-obvious
|
||||
- [ ] **Task 1.4**: Conductor - User Manual Verification "Phase 1: 5 Open Questions Resolved" (Protocol in workflow.md)
|
||||
- Ask the user to confirm the decisions.md captures the answers correctly
|
||||
- Commit decisions.md with git note summarizing the 5 answers
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Execute the Workflow on the First Target (~30-60 min)
|
||||
|
||||
Focus: produce the locked design contract for the Discussion Hub per-entry panel (`gui_2.py:3770`). The output is `designs/discussion_hub_per_entry_v1.md` (per the spec's Phase 2 deliverable).
|
||||
|
||||
- [ ] **Task 2.1**: Establish the boundary (per the spec's §3.2)
|
||||
- **WHERE**: this conversation
|
||||
- **WHAT**: confirm the boundary: inside = one entry, header + body + footer, all 7 A-ops; outside = discussion selector (B6) + discussion-level controls (B1-B11) + thinking-trace widget
|
||||
- **HOW**: post the spec's §3.2 boundary as a checklist; user confirms or adjusts
|
||||
- **SAFETY**: boundary disagreements are normal; if the user wants a different boundary, update the spec's §3.2 *first*, then proceed
|
||||
- [ ] **Task 2.2**: Audit the current implementation (so the first draft is grounded)
|
||||
- **WHERE**: `src/gui_2.py:3770 render_discussion_entry` (100+ lines)
|
||||
- **WHAT**: list every widget, every state read, every state write, every interaction
|
||||
- **HOW**: read the function in full; produce a 1-page summary "what the current per-entry panel does" (no judgments, just facts)
|
||||
- [ ] **Task 2.3**: ASCII sketch (round 1, Tier-1 first draft)
|
||||
- **WHERE**: this conversation
|
||||
- **WHAT**: first ASCII sketch of the redesigned panel (using the user's chosen vocabulary from Q1)
|
||||
- **HOW**: follow the workflow's Step 3 (per `docs/reports/ascii_sketch_ux_workflow_20260608.md` §1 Step 3); the sketch is *what the panel will look like after the redesign*, not the current state
|
||||
- **SAFETY**: don't try to make it perfect. First drafts are for the user to react to.
|
||||
- [ ] **Task 2.4**: User critique → Tier-1 revision (round 2, 3 if needed)
|
||||
- **WHERE**: this conversation
|
||||
- **WHAT**: the user critiques; the Tier-1 revises
|
||||
- **HOW**: 1 round = 1 revision from Tier-1, 1 critique from the user; the workflow caps at 3 rounds before falling back to `MiniMax understand_image`
|
||||
- [ ] **Task 2.5**: Lock the design (when the user says "that's it")
|
||||
- **WHERE**: `conductor/tracks/manual_ux_validation_20260608/designs/discussion_hub_per_entry_v1.md`
|
||||
- **WHAT**: 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)
|
||||
- **HOW**: copy the locked ASCII into the design doc; enumerate the interactions explicitly (don't say "click does X" without listing what X is); enumerate the states
|
||||
- [ ] **Task 2.6**: Conductor - User Manual Verification "Phase 2: Design Contract Locked" (Protocol in workflow.md)
|
||||
- Ask the user to confirm the design contract in `designs/discussion_hub_per_entry_v1.md` is final
|
||||
- Commit the design doc with git note summarizing the locked design + the SSDL principles applied (if any) per spec §2.6
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Implement the Design (~1-3 hours, TDD)
|
||||
|
||||
Focus: implement the locked design in `src/gui_2.py:3770` per the contract. TDD-style: write tests for the A1-A7 operations, watch them fail, implement, watch them pass.
|
||||
|
||||
- [ ] **Task 3.1**: Add the `live_gui` test fixture baseline check
|
||||
- **WHERE**: `tests/conftest.py` (or the appropriate test file)
|
||||
- **WHAT**: verify the existing `live_gui` fixture works (per `docs/guide_testing.md`); the new tests will use it
|
||||
- **HOW**: `uv run pytest tests/test_gui_discussion_entry_smoke.py -k smoke` (or whatever pre-existing smoke test exists)
|
||||
- **SAFETY**: if the live_gui fixture is broken, fix that FIRST before writing new tests (per the pre-flight check pattern in `conductor/workflow.md`)
|
||||
- [ ] **Task 3.2**: Write failing tests for A1 (collapse/expand)
|
||||
- **WHERE**: `tests/test_render_discussion_entry_collapse.py` (new)
|
||||
- **WHAT**: test that `gui_2.py:3770 render_discussion_entry` correctly toggles the `entry["collapsed"]` flag when the +/- button is clicked; test that the body is hidden when collapsed and visible when expanded
|
||||
- **HOW**: use `live_gui` fixture + Hook API; render the discussion hub; click the +/- button; assert the body is/isn't visible
|
||||
- **SAFETY**: handle the "defer-not-catch" pattern for `imgui.save_ini_settings_to_memory` per `conductor/workflow.md`'s 2026-06-05 pitfall; use the `_ini_capture_ready` flag
|
||||
- [ ] **Task 3.3**: Write failing tests for A2 (edit/read toggle)
|
||||
- **WHERE**: `tests/test_render_discussion_entry_edit_toggle.py` (new)
|
||||
- **WHAT**: test that the [Edit]/[Read] button correctly toggles `entry["read_mode"]`; test that the body shows an `input_text_multiline` when in edit mode, plain text when in read mode
|
||||
- [ ] **Task 3.4**: Write failing tests for A3 (role change via combo)
|
||||
- **WHERE**: `tests/test_render_discussion_entry_role.py` (new)
|
||||
- **WHAT**: test that the role combo correctly changes `entry["role"]` when a new role is selected from `app.disc_roles`; test that the role-tinted background updates
|
||||
- [ ] **Task 3.5**: Write failing tests for A4 + A5 (insert before / insert after)
|
||||
- **WHERE**: `tests/test_render_discussion_entry_insert.py` (new)
|
||||
- **WHAT**: test that clicking [Ins] creates a new entry above/below; test that the new entry has the default role + empty content
|
||||
- [ ] **Task 3.6**: Write failing tests for A6 (delete)
|
||||
- **WHERE**: `tests/test_render_discussion_entry_delete.py` (new)
|
||||
- **WHAT**: test that clicking [Del] removes the entry from `app.disc_entries`; test that the HistoryManager (per `docs/guide_state_lifecycle.md`) captures the deletion in the undo stack
|
||||
- [ ] **Task 3.7**: Write failing tests for A7 (branch)
|
||||
- **WHERE**: `tests/test_render_discussion_entry_branch.py` (new)
|
||||
- **WHAT**: test that clicking [Branch] calls `project_manager.branch_discussion` with the current entry as the branch point; test that a new take is created
|
||||
- [ ] **Task 3.8**: Run the full A1-A7 test suite; confirm all 7 fail (Red phase)
|
||||
- **WHERE**: shell
|
||||
- **WHAT**: `uv run pytest tests/test_render_discussion_entry_*.py -v`
|
||||
- **HOW**: expect 7 failures (or skips) for the new tests; the old code doesn't match the new design
|
||||
- **SAFETY**: if any test passes for the wrong reason, investigate before proceeding
|
||||
- [ ] **Task 3.9**: Implement the redesign in `gui_2.py:3770`
|
||||
- **WHERE**: `src/gui_2.py:3770 render_discussion_entry` (modify; ~100+ lines → ~150-200 lines depending on design)
|
||||
- **WHAT**: implement the locked design from `designs/discussion_hub_per_entry_v1.md`
|
||||
- **HOW**: follow the locked sketch literally; every widget, every state, every interaction should match the contract; if the implementation diverges, update the contract first
|
||||
- **SAFETY**: keep the per-entry thinking-trace widget in its own function (it's already separated per `docs/guide_discussions.md`); don't refactor what isn't in scope
|
||||
- [ ] **Task 3.10**: Run the A1-A7 tests; confirm all 7 pass (Green phase)
|
||||
- **WHERE**: shell
|
||||
- **WHAT**: `uv run pytest tests/test_render_discussion_entry_*.py -v`
|
||||
- **HOW**: expect 7 passes; if any fails, debug and fix (do NOT mark task complete with failing tests; do NOT add `@pytest.mark.skip` without explicit user approval)
|
||||
- [ ] **Task 3.11**: Run the full test suite to confirm no regressions
|
||||
- **WHERE**: shell
|
||||
- **WHAT**: `uv run pytest tests/ --timeout=60` (small batches of 4 max per workflow.md; the live_gui tests are sensitive)
|
||||
- **HOW**: batch as: (a) unit tests for gui_2.py; (b) live_gui tests; (c) any test that imports the discussion system; run each batch separately
|
||||
- **SAFETY**: per the workflow.md "do not run the full suite" rule; use targeted batches
|
||||
- [ ] **Task 3.12**: Verify with `MiniMax understand_image` (per Q2 decision from Phase 1)
|
||||
- **WHERE**: shell + `MiniMax understand_image` tool
|
||||
- **WHAT**: render the actual GUI; take a screenshot of the redesigned per-entry panel; compare the screenshot to the locked ASCII sketch
|
||||
- **HOW**: if Q2 = "always", this is mandatory; if "only on mismatch", this is conditional on Tier-3 reporting a mismatch
|
||||
- **SAFETY**: if the screenshot reveals deltas from the sketch, update the sketch to match the actual implementation (the sketch is a contract, not a wish; if reality differs, fix the sketch first, then the code)
|
||||
- [ ] **Task 3.13**: Atomic commit per task pattern
|
||||
- **WHERE**: git
|
||||
- **WHAT**: commit each test file separately (per workflow.md "atomic per-task commits")
|
||||
- **HOW**: `git add tests/test_render_discussion_entry_*.py; git commit -m "test(gui): failing tests for A1-A7 operations on render_discussion_entry"` (one commit per test file or one commit per group of 2 related tests; not a single big commit)
|
||||
- [ ] **Task 3.14**: Final commit for the implementation
|
||||
- **WHERE**: git
|
||||
- **WHAT**: commit the modified `src/gui_2.py:3770` + the design doc
|
||||
- **HOW**: `git add src/gui_2.py conductor/tracks/manual_ux_validation_20260608/designs/; git commit -m "feat(gui): implement Discussion Hub per-entry panel redesign per locked ASCII contract"`
|
||||
- [ ] **Task 3.15**: Attach git notes per the workflow.md protocol
|
||||
- **WHERE**: git
|
||||
- **WHAT**: for the implementation commit, attach a git note summarizing the 7 A-ops, the 1-3 design rounds, the test count, the MiniMax verification result, and the SSDL principles applied (if any)
|
||||
- [ ] **Task 3.16**: Conductor - User Manual Verification "Phase 3: Implementation Complete" (Protocol in workflow.md)
|
||||
- Ask the user to confirm the implementation matches the locked design
|
||||
- Update `state.toml` to mark all Phase 3 tasks complete with the commit SHAs
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Document the Pattern + Identify Next Targets (~15 min)
|
||||
|
||||
Focus: capture the workflow learnings, update the workflow report with the answered Q1-Q5, and propose the next 5-7 targets.
|
||||
|
||||
- [ ] **Task 4.1**: Update `docs/reports/ascii_sketch_ux_workflow_20260608.md`
|
||||
- **WHERE**: the workflow report
|
||||
- **WHAT**: §7 "Open questions for the user" → "Resolved Q1-Q5 (per `decisions.md` of this track)"
|
||||
- **HOW**: replace §7 with the 5 answers; cite `decisions.md`; keep the alternatives in the section as historical record
|
||||
- [ ] **Task 4.2**: Write `next_targets.md` (5-7 candidate panels)
|
||||
- **WHERE**: `conductor/tracks/manual_ux_validation_20260608/next_targets.md`
|
||||
- **WHAT**: list 5-7 panels that would benefit from the workflow, in priority order
|
||||
- **HOW**: each entry is: (a) panel name + file:line; (b) why it's a good candidate; (c) estimated design effort; (d) the user-facing operation matrix or A-op equivalent; (e) any SSDL defusing opportunities
|
||||
- **CANDIDATES** (from the workflow report's §1):
|
||||
1. Context Panel file row (`gui_2.py` Files & Media → Files)
|
||||
2. Discussion-level controls (B1-B11) — `gui_2.py:4239 render_discussion_entry_controls`
|
||||
3. MMA spawn-approval modal — `gui_2.py:5163+`
|
||||
4. Vendor State tab (post-Vendor-Capability-Matrix ship) — `gui_2.py` Operations Hub
|
||||
5. Persona editor modal
|
||||
6. Keep Pairs widget (per the UI Polish Phase 2 work) — `gui_2.py:3829`
|
||||
7. Truncate/Compress/Save discussion panel (per the UI Polish Phase 2 work)
|
||||
- [ ] **Task 4.3**: Commit the docs + next-targets
|
||||
- **WHERE**: git
|
||||
- **WHAT**: commit the workflow update + next_targets.md
|
||||
- **HOW**: separate commits for clarity
|
||||
- [ ] **Task 4.4**: Update `conductor/tracks.md` to mark this track as complete
|
||||
- **WHERE**: `conductor/tracks.md`
|
||||
- **WHAT**: move the track from the "Active" / "Backlog" section to the "Recently Archived" section; add a brief summary
|
||||
- **HOW**: the track is shipped but not yet archived; archive when the user says so or when the next track is specced
|
||||
- [ ] **Task 4.5**: Conductor - User Manual Verification "Phase 4: Pattern Documented" (Protocol in workflow.md)
|
||||
- Ask the user to confirm the docs + next_targets capture the work
|
||||
- This is the final user-verification checkpoint for the entire track
|
||||
|
||||
---
|
||||
|
||||
## Total Tasks: 21 (across 4 phases)
|
||||
|
||||
| Phase | Tasks | Effort | User-Interactive? |
|
||||
|---|---|---|---|
|
||||
| 1 | 4 | ~5 min | YES (5 questions) |
|
||||
| 2 | 6 | ~30-60 min | YES (1-3 ASCII rounds) |
|
||||
| 3 | 16 | ~1-3 hours | PARTIAL (verification checkpoints) |
|
||||
| 4 | 5 | ~15 min | PARTIAL (final verification) |
|
||||
|
||||
**The track is mostly the user's time** (Phase 1, Phase 2 rounds, the verification checkpoints). The Tier-2/Tier-3 effort is concentrated in Phase 3 (TDD implementation).
|
||||
|
||||
---
|
||||
|
||||
## Cross-References
|
||||
|
||||
- The 4-phase plan maps to `spec.md` §4
|
||||
- The TDD pattern (Red → Green → Refactor) is per `conductor/workflow.md` §"Standard Task Workflow"
|
||||
- The atomic commit pattern is per `conductor/workflow.md` §"Commit Guidelines"
|
||||
- The git notes pattern is per `conductor/workflow.md` §"Attach Task Summary with Git Notes"
|
||||
- The MiniMax understand_image comparison is per `docs/reports/ascii_sketch_ux_workflow_20260608.md` §4
|
||||
- The SSDL cross-reference is per `spec.md` §2.6
|
||||
|
||||
---
|
||||
|
||||
*End of plan. Begin with Phase 1 (5 questions to the user).*
|
||||
@@ -0,0 +1,270 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,108 @@
|
||||
# Track state for manual_ux_validation_20260608_PLACEHOLDER
|
||||
# Workflow + first-target redesign; 4 phases
|
||||
# Updated by Tier 2 Tech Lead as phases complete
|
||||
|
||||
[meta]
|
||||
track_id = "manual_ux_validation_20260608_PLACEHOLDER"
|
||||
name = "Manual UX Validation — ASCII-Sketch Workflow"
|
||||
status = "active"
|
||||
current_phase = 1 # Phase 1: Resolve the 5 Open Questions
|
||||
last_updated = "2026-06-08"
|
||||
|
||||
[blocked_by]
|
||||
# No blockers; track is independent
|
||||
none = "no blockers"
|
||||
|
||||
[blocks]
|
||||
# Future follow-up tracks (promoted from next_targets.md after Phase 4)
|
||||
discussion_hub_redesign_20260608_PLACEHOLDER = "potential follow-up; promoted from next_targets.md after Phase 4"
|
||||
context_panel_redesign_20260608_PLACEHOLDER = "potential follow-up; promoted from next_targets.md after Phase 4"
|
||||
mma_spawn_modal_redesign_20260608_PLACEHOLDER = "potential follow-up; promoted from next_targets.md after Phase 4"
|
||||
|
||||
[phases]
|
||||
phase_1 = { status = "pending", checkpointsha = "", name = "Resolve the 5 Open Questions" }
|
||||
phase_2 = { status = "pending", checkpointsha = "", name = "Execute Workflow on First Target" }
|
||||
phase_3 = { status = "pending", checkpointsha = "", name = "Implement the Design" }
|
||||
phase_4 = { status = "pending", checkpointsha = "", name = "Document the Pattern + Identify Next Targets" }
|
||||
|
||||
[tasks]
|
||||
# Phase 1: Resolve the 5 Open Questions
|
||||
t1_1 = { status = "pending", commit_sha = "", description = "Initialize MMA Environment (activate_skill mma-orchestrator)" }
|
||||
t1_2 = { status = "pending", commit_sha = "", description = "Pose the 5 open questions to the user (one at a time, with defaults)" }
|
||||
t1_3 = { status = "pending", commit_sha = "", description = "Write decisions.md capturing the 5 answers" }
|
||||
t1_4 = { status = "pending", commit_sha = "", description = "Conductor - User Manual Verification 'Phase 1: 5 Open Questions Resolved'" }
|
||||
|
||||
# Phase 2: Execute the Workflow on the First Target
|
||||
t2_1 = { status = "pending", commit_sha = "", description = "Establish the boundary (per spec §3.2)" }
|
||||
t2_2 = { status = "pending", commit_sha = "", description = "Audit the current gui_2.py:3770 implementation (1-page summary)" }
|
||||
t2_3 = { status = "pending", commit_sha = "", description = "ASCII sketch round 1 (Tier-1 first draft)" }
|
||||
t2_4 = { status = "pending", commit_sha = "", description = "User critique → Tier-1 revision (rounds 2, 3 if needed)" }
|
||||
t2_5 = { status = "pending", commit_sha = "", description = "Lock the design: write designs/discussion_hub_per_entry_v1.md" }
|
||||
t2_6 = { status = "pending", commit_sha = "", description = "Conductor - User Manual Verification 'Phase 2: Design Contract Locked'" }
|
||||
|
||||
# Phase 3: Implement the Design (TDD)
|
||||
t3_1 = { status = "pending", commit_sha = "", description = "Add live_gui fixture baseline check" }
|
||||
t3_2 = { status = "pending", commit_sha = "", description = "Write failing tests for A1 (collapse/expand)" }
|
||||
t3_3 = { status = "pending", commit_sha = "", description = "Write failing tests for A2 (edit/read toggle)" }
|
||||
t3_4 = { status = "pending", commit_sha = "", description = "Write failing tests for A3 (role change via combo)" }
|
||||
t3_5 = { status = "pending", commit_sha = "", description = "Write failing tests for A4 + A5 (insert before/after)" }
|
||||
t3_6 = { status = "pending", commit_sha = "", description = "Write failing tests for A6 (delete)" }
|
||||
t3_7 = { status = "pending", commit_sha = "", description = "Write failing tests for A7 (branch)" }
|
||||
t3_8 = { status = "pending", commit_sha = "", description = "Run A1-A7 test suite; confirm 7 fail (Red phase)" }
|
||||
t3_9 = { status = "pending", commit_sha = "", description = "Implement the redesign in gui_2.py:3770" }
|
||||
t3_10 = { status = "pending", commit_sha = "", description = "Run A1-A7 tests; confirm 7 pass (Green phase)" }
|
||||
t3_11 = { status = "pending", commit_sha = "", description = "Run full test suite; confirm no regressions" }
|
||||
t3_12 = { status = "pending", commit_sha = "", description = "Verify with MiniMax understand_image (per Q2 decision)" }
|
||||
t3_13 = { status = "pending", commit_sha = "", description = "Atomic commit per task (test files separate)" }
|
||||
t3_14 = { status = "pending", commit_sha = "", description = "Final commit for the implementation" }
|
||||
t3_15 = { status = "pending", commit_sha = "", description = "Attach git notes per workflow.md protocol" }
|
||||
t3_16 = { status = "pending", commit_sha = "", description = "Conductor - User Manual Verification 'Phase 3: Implementation Complete'" }
|
||||
|
||||
# Phase 4: Document the Pattern + Identify Next Targets
|
||||
t4_1 = { status = "pending", commit_sha = "", description = "Update docs/reports/ascii_sketch_ux_workflow_20260608.md with answered Q1-Q5" }
|
||||
t4_2 = { status = "pending", commit_sha = "", description = "Write next_targets.md (5-7 candidate panels)" }
|
||||
t4_3 = { status = "pending", commit_sha = "", description = "Commit the docs + next-targets" }
|
||||
t4_4 = { status = "pending", commit_sha = "", description = "Update conductor/tracks.md to reflect track status" }
|
||||
t4_5 = { status = "pending", commit_sha = "", description = "Conductor - User Manual Verification 'Phase 4: Pattern Documented'" }
|
||||
|
||||
[verification]
|
||||
# Track verification criteria
|
||||
spec_md_exists = true
|
||||
plan_md_exists = true
|
||||
metadata_json_exists = true
|
||||
state_toml_exists = true
|
||||
index_md_exists = true
|
||||
|
||||
# 5 open questions documented with defaults
|
||||
open_questions_documented = true
|
||||
open_questions_defaults_documented = true
|
||||
|
||||
# SSDL cross-reference in spec §2.6
|
||||
ssdl_cross_reference_documented = true
|
||||
|
||||
# 4 phases planned with 21 tasks
|
||||
plan_phases_documented = true
|
||||
plan_tasks_documented = true
|
||||
|
||||
# First target specified
|
||||
first_target_specified = true # Discussion Hub per-entry panel (gui_2.py:3770)
|
||||
|
||||
# No code modified yet
|
||||
no_code_modified_yet = true
|
||||
|
||||
[ssdl_alignment]
|
||||
# Per spec §2.6, GUI ASCII and SSDL are different vocabularies for different purposes
|
||||
gui_ascii_for_panel_design = true
|
||||
ssdl_for_internal_refactoring = true
|
||||
conflation_warning_documented = true
|
||||
|
||||
# SSDL principles that may inform Phase 3 internal refactoring
|
||||
nil_sentinel_pattern_available = true # For entry.get("collapsed") defusing
|
||||
generational_handle_pattern_available = true # For entry references across frames
|
||||
effective_codepath_pattern_available = true # For the 4-5 branches in render_discussion_entry
|
||||
immediate_mode_pattern_available = true # For the role combo (immediate-mode vs retained-mode)
|
||||
xar_chunkification_pattern_available = false # Not relevant for a single-panel GUI render
|
||||
|
||||
[status]
|
||||
# Active; Phase 1 is the current phase
|
||||
status = "active (Phase 1: awaiting 5 user answers to open questions)"
|
||||
Reference in New Issue
Block a user