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