Skip to content

Commit dea250f

Browse files
committed
docs(diff-ux): add §3.13 — two blind independent redesigns, convergence, and adoptions
Two designers were given only the task list and research evidence (the existing Fresh UI and this doc's workspace design withheld) and asked to design the review TUI from scratch. Both independently converged with the workspace on the same skeleton — comparison-as-identity, section tree, selection-drives-preview, relabeling verbs, hash-keyed viewed marks, resume-leads-with-delta, undo over confirmation, runnable help — which de-risks the §3 core. The section presents each alternative's distinctive ideas with one representative frame and a verdict table, keeps the genuine differences explicit (chips vs hint bar, cycling rail, in-workspace presets), and ends with the adoption list: uppercase-escalation keymap rule, C conclude verb, runnable-help-as-palette, persisted undo journal via git objects, waiting-on-you session ordering, narrative default order for agent scopes, live-update queueing, symbol-graph reject guard, last-review default target, interdiff pseudo-commit, noise out of the progress denominator, command log, and the sub-100-col zoom model. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01756Rh35n65zC4xHQcQAqBL
1 parent 5f79689 commit dea250f

1 file changed

Lines changed: 121 additions & 0 deletions

File tree

docs/internal/unified-diff-experience-design.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -616,6 +616,127 @@ column (→ notes rail + inline boxes), the two-line hint bar (→ scope bar +
616616
context line + chips), the separate picker dialog (→ scope-choosing state),
617617
and the separate History tab (→ history preset + commits lens).
618618

619+
### 3.13 Independent redesigns: two blind alternatives, and what to take from them
620+
621+
To pressure-test §3.1–3.12, two designers were given the same brief — the task
622+
list (§ Tasks) and the research evidence (§2) only, with the existing Fresh UI
623+
and this document's workspace design deliberately withheld — and asked to
624+
design a TUI review experience from a blank slate. Their full documents are
625+
preserved with the session research notes; this section presents each design's
626+
distinctive ideas and the resulting decisions.
627+
628+
**The headline is the convergence.** Working blind, both designs and the
629+
workspace (§3.2–3.9) independently arrived at the same skeleton:
630+
631+
- the comparison (`base ⟶ target`) as an always-visible, clickable, editable
632+
control that *is* the review's identity — every source a preset of it;
633+
- a magit-style typed section tree with persistent folds and depth presets;
634+
- a navigator whose selection reactively drives a read-only diff projection
635+
(`Enter` = portal to the live buffer; never a second writable copy);
636+
- verbs that relabel per source on unchanged keys (stage/discard ⇄
637+
keep/reject), shown in-place so nothing is hidden;
638+
- viewed marks keyed by content hash, mark-and-advance, resume that leads
639+
with "what changed since I last looked";
640+
- undo instead of confirmation prompts, with the real git command echoed;
641+
- runnable `?` help; noise quarantined by default; one-column marker
642+
scrollbar as the review's map.
643+
644+
Three independent derivations from the same evidence landing on the same core
645+
is the strongest de-risking signal this document has: **the §3 skeleton is not
646+
one designer's taste.** The interesting material is where they differ.
647+
648+
#### Alternative A — "Ledger" (outline-first, conclude-verb design)
649+
650+
One frame (agent session; note the narrative ordering and the inline guard):
651+
652+
```
653+
◆ Review: session fix-flaky-tests base session-start ▾ ⟶ head worktree (live ◉)
654+
agent: working… · kept 9 · rejected 2 · open 7 · viewed 11/18 · Flat ▾
655+
├──────────────────────────────┬────────────────────────────────────────────────────┤
656+
│ narrative order (agent's) ▾ │ ⌁ fn wait_for_port() · tests/util.rs │
657+
│ ✓ tests/util.rs kept │ 88│ 88▎ let deadline = Instant::now() + timeout;│
658+
│ ✗ tests/flaky.rs rejected│ 89│ ▁ «sleep(500)» │
659+
│ ▸· tests/net.rs ↺ changed│ │ 89▎ «backoff.retry(|| probe(port))» │
660+
│ · src/backoff.rs ● new │ ⚠ tests/net.rs:14 (kept) calls probe(port) — │
661+
│ ▸ 12 more (unreviewed) │ rejecting this hunk removes its definition. │
662+
├──────────────────────────────┴────────────────────────────────────────────────────┤
663+
│ hunk: s keep · x reject · v viewed · c note · N next open · live: files update │
664+
```
665+
666+
Distinctive ideas, with verdicts:
667+
668+
| Idea | Verdict for the workspace |
669+
|---|---|
670+
| **Uppercase escalates lowercase** (`v` viewed → `V` unmark; `c` comment → `C` *conclude*; one rule makes the map guessable) | **Adopt the rule** as a keymap design principle; `C` = conclude (commit / submit / finish) fills a gap — the workspace had completion *exits* but no single conclude verb |
671+
| **`?` help = runnable, filterable command list** (help and palette are one thing) | **Adopt** (both designs had it; §3.7 said "runnable" — make it the palette itself, scoped) |
672+
| **Undo journal persisted across restarts**, discarded hunks saved as patch files | **Adopt**; upgrade §3.1 principle 9 from "session undo" to journal-backed |
673+
| **Entry rows sorted "waiting on you" first** with per-session progress sparklines | **Adopt** in the scope presets |
674+
| **Narrative order (agent's edit sequence) as the default file order in agent scopes** | **Adopt as the default** there (deterministic — it's the edit log, not an AI summary; path order one toggle away) |
675+
| Comments have **no panel at review width** — inline pills only; a comments rail exists only ≥160 cols | Partial: keep the notes rail as a cycled projection (a severity-sorted index of a 50-file review is worth a rail), but adopt the **wide-screen anchored rail** for ≥160 cols |
676+
| `v` = viewed (because `Space` = extend selection) | Keep `Space` = advance (§3.6); selection stays on `v`/drag — the burn-down key deserves the biggest key |
677+
678+
#### Alternative B — the "lens" design (take/untake/drop, live-queue design)
679+
680+
One frame (the live-update queue and the symbol-graph guard — its two best
681+
ideas — visible together):
682+
683+
```
684+
┌ Review ▸ session lexer-rewrite start ⇄ now ● agent working ▰▰▰▱ 11/18 · [s 1/3]┐
685+
├──────────────────────────────┬─────────────────────────────────────────────────────┤
686+
│ ▾ To review (7) │ src/parser/lex.rs › fn next_token() │
687+
│ ▸ ▾ src/parser/lex.rs ↻2 │ 150 ─ let c = self.peek(); │
688+
│ ▾ fn next_token() │ 150 + let Some(c) = self.peek() else { │
689+
│ hunk @201 NEW │ ┌─────────────────────────────────────────────────┐│
690+
│ ▾ Rejected (2) │ │ ⚠ rejecting this hunk conflicts with 2 KEPT ││
691+
│ Sessions needing review: │ │ hunks that call `peek()`'s new signature: ││
692+
│ ▸1 lexer-rewrite ● 7 left │ │ mod.rs @44 · ast.rs @210 ││
693+
│ 2 fix-ci ✓ 3 left │ │ x reject those too · Enter reject anyway ││
694+
├──────────────────────────────┴─────────────────────────────────────────────────────┤
695+
│ s keep · x reject · u unkeep · N jump to 2 new changes · ]s next session · ? help │
696+
```
697+
698+
Distinctive ideas, with verdicts:
699+
700+
| Idea | Verdict for the workspace |
701+
|---|---|
702+
| **Live-update queueing**: files you're inside queue agent edits behind a `↻N` badge (`N` applies and jumps); other files refresh freely — *content never moves under your cursor* | **Adopt verbatim** — the best answer found to watch-mode vs. rug-pull, stronger than plain watch |
703+
| **Symbol-graph context-blindness guard**: rejecting a hunk checks identifiers it removes against identifiers *kept* hunks reference; inline warning lists the linked hunks with one-key "reject those too" | **Adopt** — replaces §3.9's cruder file-default heuristic (keep file-level default too; they compose) |
704+
| **"Since my last review" as the *default* target when reopening a previously-reviewed lens** (full range one keypress away) | **Adopt** — §3.6's resume banner asked; B's default answers |
705+
| **`⇅ interdiff` pseudo-commit** in commits lens after a force-push (v3→v5 as just another section) | **Adopt** in the commits lens |
706+
| **Noise excluded from the progress denominator** (lockfiles/generated/fmt-only don't count against 19/34) | **Adopt** — progress must measure judgment, not scrolling |
707+
| **Undo ring backed by git objects** (`refs/…/undo/*`), destructive verbs recoverable across restarts | **Adopt** as the implementation of A's journal |
708+
| **`` ` `` VCS command log** toggle (every echoed command, reviewable) | **Adopt** — cheap, completes the transparency story |
709+
| **<100-col zoom model**: one pane at a time (Esc shows the tree full-screen, Enter dives back); burn-down loop works without ever visiting the navigator | **Adopt** — cleaner than shrinking panes side-by-side at 80 cols |
710+
| **`h`/`l` widen/narrow granularity** (file ⇄ hunk ⇄ line as a ladder you climb) | Consider (conflicts with pane-focus muscle memory; prototype both) |
711+
| Verb triad named **take/untake/drop** (`s`/`u`/`x`) relabeling per lens | Naming kept as-is (stage/keep are the users' words), but the *triad symmetry* (every take has an untake) is adopted as a rule |
712+
713+
#### What stays deliberately different in the workspace design
714+
715+
- **Chips over a global hint bar.** Both alternatives keep a persistent
716+
bottom hint bar listing current verbs; the workspace puts the verb hints
717+
*on the focused section* (chip row) with a leaner context line. Chips keep
718+
eyes on the code and scale better to the web renderer; the hint bar
719+
duplicates what chips already say. (If chips test poorly for
720+
discoverability, B's hint bar is the fallback — it's the same data.)
721+
- **The rail cycles (files/commits/notes); the alternatives fix it to
722+
files+commits.** The notes projection earns its slot in marathon reviews;
723+
cycling keeps the one-rail budget.
724+
- **Scope presets open in-workspace** (§3.3's choosing state) rather than as
725+
a modal overlay picker — one less floating surface, same content.
726+
727+
#### Adoption summary (folded into the next revision of §3)
728+
729+
From A: uppercase-escalation rule; `C` conclude verb; runnable-help-as-palette;
730+
persisted undo journal; waiting-on-you session ordering; narrative default
731+
order in agent scopes; ≥160-col anchored comments rail.
732+
From B: live-update queue (`↻N`/`N`); symbol-graph reject guard; last-review
733+
default target; `` interdiff pseudo-commit; noise out of the denominator;
734+
git-object undo ring; `` ` `` command log; sub-100-col zoom model.
735+
Under prototype: `h`/`l` granularity ladder vs. pane focus; chips vs. hint bar
736+
(instrumented, not argued).
737+
738+
---
739+
619740
## 4. Part II — talking to agents and outside systems (lower priority)
620741

621742
Everything here is **orthogonal to Part I by construction**: it consumes the

0 commit comments

Comments
 (0)