Files
pipelines/docs/ui-ux-review.md
T
alan 36fad7d130 Merge lane-go: keep the lane's reviewed work
Combines lane-go's typed omni search, launch-time model overrides, TUI
artifacts view, run-state websocket push, and the "reflect the change where
it belongs" committer rule with the Templates gallery, chat/omni-search and
other reviewed work already on main. The 12 files both sides touched keep
both intents composed rather than dropping either side: the omni search keeps
the typed search contract (CLI `pipelines search` and the TUI popup with type
badges and marked snippets) alongside the run-list quick filter; cli.md and
ui-ux-review.md document both the search rework and the artifacts view;
orchestration.md, harnesses.md and operations.md keep the model-override and
reflect-where-it-belongs guidance; and the protocol/CLI/server/TUI code keeps
the new search, run-event, override and artifacts paths alongside the existing
run, title and help surfaces.

Checks before committing:
- go build ./...  -- pass
- go vet ./...  -- pass
- go test -count=1 ./internal/... ./cmd/...  -- all pass

Doc check before committing: nothing needs updating. The lane's own docs and
references (docs/cli.md, docs/ui-ux-review.md, and the orchestration,
harnesses and operations skill references) already carry the new features.
format.md and the packaged templates already describe the line-oriented result
format and the human decision stage from the earlier lane-go merge. The root
README already describes the omni search popup. Model overrides, the search
command, run events and the artifacts view are runtime/CLI/TUI surfaces that
cli.md documents; no template, README or topic-doc edit is required by this
merge.
2026-10-17 02:04:58 +01:00

9.0 KiB
Raw Blame History

UI/UX review

An independent reviewer rendered every screen family at 120×36, 80×24 and 40×16, alongside light/dark ANSI previews. This was an executed screen/render review, not a real-user usability or screen-reader study. Real-terminal contrast and external editor/OpenCode behavior were not assessed by that review.

Design decisions

  • Results before machinery. Home starts with recent outcomes and reported results. Statistics come afterward; addresses and notification setup live in Status.
  • Two Run focus targets. Tab and Shift+Tab alternate Details ↔ Graph. Recorded visits are a compact selector inside Details, not a third focusable pane.
  • Readable reports. Results use prose, Markdown, lists and labelled nested values instead of raw transport objects. The stored output is unchanged.
  • Progressive disclosure. Progress, task input, evidence and execution metadata are secondary. A stage's reported result is not independently verified success.
  • Full-size graphs. Keep the existing boxes/arrows, centering, dim pending routes and panning. Collapse an unusably small inactive run-graph preview rather than drawing severed box tops. A focused graph remains reachable on narrow screens.
  • Contextual controls. Forms and overlays replace background-page hints. Safety warnings wrap and scroll while confirmation/cancellation remain pinned.

Feedback by screen

Screen Reviewer feedback Response / remaining work
Home Usage and infrastructure outrank results; narrow columns clip reports. Results first, wider result column, wrapped previews, statistics last, continuation indicator.
Home empty/loading Missing statistics look like permanent loading. No placeholder usage spinner; empty and initial data-loading states are distinct.
Pipeline overview Graph is good; identity and metadata compete with useful content. Keep the graph. Further compacting the toolbar on small screens remains worthwhile.
Pipeline stage Five prose columns resemble a spreadsheet. Full-width stacked fields; capabilities before long instructions; configuration disclosure.
Runs list Footer advertises stage/graph controls that do not apply. List-specific search/select/open/back controls.
Run overview Stage sidebar takes too much space and adds a third focus target. Remove sidebar focus and resizing; compact visit selector and full-width Details.
Run stage/visit Summary repeats output; long evidence crowds the result. Render the result once; collapse secondary sections; preserve each recorded visit.
Run graph Inactive previews sever boxes; narrow focused Graph can disappear. Collapse unusable previews; allocate the viewport to the focused full-size canvas.
Templates Definition source dominates purpose and expected result. Error/loading states corrected. A purpose-first catalog overview remains a follow-up.
Drafts Paths and publication metadata dominate the draft's purpose. Preserve current draft retention/validation. Moving metadata behind disclosure remains a follow-up.
Status Narrow cards hide addresses; scrolling does not reveal them. Wrap card contents and scroll the actual service-card canvas.
Task form Tool lists consume prompt space; wrong footer. Larger task area, compact scope summary, correct submit/cancel controls.
CLI pipeline picker Background Home controls remain visible. Picker-specific filter/select/cancel controls.
Search "Omnisearch" promises broader scope than pipeline search. Home / opens an omni popup that searches pipelines, versions, runs, steps/visits, artifact names and stage input/output/evidence text, with typed badges, a non-colour marked snippet for text matches, and Enter-to-open navigation. The run-list / filter remains a separate, pipeline-scoped quick filter. The same broad cross-kind search is available server-side as pipelines search QUERY [--type KIND], documented in CLI and agent authoring.
Commands No descriptions or indication of hidden entries. Selected-command explanation and visible range/count.
Versions Selected/latest markers truncate on narrow screens. Correct view-version footer; further metadata prioritization remains a follow-up.
Naming/publication Naming inherits publication shortcuts. Input-specific name-saving/retention footer.
Start/retry/cancel Narrow safety warnings are clipped. Wrapped, independently scrollable disclosures with pinned controls.
Editor picker/checking Unlabelled filter and color-only selection; wrong pending footer. Labelled filter, textual selection marker, appropriate pending-state footer.
Logs Long failure messages are horizontally inaccessible. Left/right panning; vertical unread tracking is retained.
Failure/debug Generic mutation warning does not explain Debug. Explain pinned definition/evidence, retained draft scope and separation from retry.

The second executed review confirmed the improved Home and 80-column run report hierarchy. It identified four remaining narrow-layout issues, addressed afterward: short-screen Details now uses compact headers to expose the actual result; pipeline stage focus collapses its inactive graph preview; draft-delete uses the same wrapped/scrollable safety dialog; and narrow overlay footers keep Escape instructions visible. Dedicated regressions exercise each of these behaviors.

Navigation

Run opens in Details. n/p selects recorded visits from either pane, including repeated stages; 0 returns to the overview. j/k scrolls Details or pans Graph, depending on focus. h/l and arrow keys pan a focused graph; in Details, left/right selects the previous/next visit. c centers the focused graph. o, s, i, t, m disclose result, progress, input, evidence and execution details. A opens the run's artifacts view: recorded files grouped by stage and visit, with name, content type and human size in aligned columns, an [img] marker for images, the URL per entry, and Enter/o to open or y to copy the selected entry.

Home still advertises only / search and : commands. q never exits the client; use :quit. Consequential actions still require explicit confirmation.

Regression coverage

internal/tui/ux_regression_test.go covers the two-target focus cycle at all three sizes, visible narrow graph focus, readable nested reports without altering data, reachable safety warnings, contextual footers, terminal errors and narrow Status scrolling. Existing graph, repeated-visit, permission, draft and confirmation tests remain applicable. Compiled CLI/TUI PTY integration additionally exercises the actual two-target Tab cycle and editor/publication/debug/retry flows with mocked OpenCode; it does not verify real-provider inference or terminal-specific contrast.

Earlier review record: October 8, 2026

The retained review below predates this redesign. Its findings and verification are historical, not a claim that the current screens have no remaining UX issues.

Five independent read-only reviewer sessions inspected executed Model.View renders of Home, pipeline details, selected/focused/scrolled stages, native delivery, and run inspection at 80/120/160 columns. Fixes were applied between rounds. Snapshot review does not establish color accessibility or phone delivery.

Earlier round Findings and changes
1 Added stage row ranges, horizontal graph overflow arrows/pan hint, and full-height column separators.
2 Balanced graph/detail space; expanded focused details; added textual focus/selection and complete selected-run headings; made title truncation explicit.
3 Exposed tools/notify in narrow configuration columns; preserved run statuses separately from shortened names; corrected run page size.
4 Made pinned field headings follow the actual scrolled group; exposed page-scroll keys; preserved HTTP/HTTPS in compact endpoint text.
5 No material remaining usability findings in those reviewed renders.

That iteration added wrapping n/p pipeline-stage selection and placed the ntfy URL/topic in the global header. This redesign supersedes that header placement and the multi-column stage layout; it preserves pipeline-stage selection.

The earlier record reports race tests, vet, builds, and actual PTY inspection of the historical anime episodes today v1 pipeline (pipeline 8, no schedule). Its complete model/web/phone execution was not tested. It used dated web evidence → verify/enrich → Markdown report → native ntfy attachment through the system connection; the LiveChart schedule was fetched during that investigation. Removing its bundled starter does not remove its published history. Current snapshot fixtures use the generic examples/three-stage.md starter.

PIPELINES_UX_SNAPSHOT_DIR=<directory> go test ./internal/tui -run TestUIUXReviewSnapshots -count=1 regenerates the existing snapshots without server mutations. Review artifacts remain in the session's approved temporary directory.