From ba06d904f0e0566e9eef793e6ca4dc5c4bd9b872 Mon Sep 17 00:00:00 2001 From: prosolis <5590409+prosolis@users.noreply.github.com> Date: Mon, 27 Jul 2026 22:20:54 -0700 Subject: [PATCH] UX review: correct the item 3b handoff advice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous handoff sent the next session off to read feat/mechanics-deterministic-pass and feat/calm-suggestions as unmerged branches. Both are in main and have been for a while — that came from misreading `git branch -vv` tracking info as merge status. It matters because it inverts the advice. The deterministic rules engine (prose.ts) already ships, already emits exact-span fixes as suggestion cards under a 'mechanics' family, and already suppresses re-edits of settled sentences. So item 3b's remaining work is most likely the latency/ordering half — render local hits before the LLM pass — not writing a rules engine. Point at the code and the two commits instead. Same for item 5: internal/suggestions/translate.go already exists. Also record that every topic branch was fully merged and has now been deleted locally and on origin; main is the only branch left. Claude-Session: https://claude.ai/code/session_016y6gyuHkQXPiEuW8RGQyua --- UX_REVIEW_2026-07-27.md | 42 ++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/UX_REVIEW_2026-07-27.md b/UX_REVIEW_2026-07-27.md index f1d9a03..951dc57 100644 --- a/UX_REVIEW_2026-07-27.md +++ b/UX_REVIEW_2026-07-27.md @@ -289,15 +289,34 @@ if you're comparing against memory of the live site, that's why. reproducible) and item 5's original premise (re-scoped, much cheaper now). **Untouched:** items 2, 3, 4, 6, 7, 8. -**Suggested next:** item 3b, the instant local rules layer — best -value-for-effort left, no server work, and it's the item that most matches -the "LLM is garnish" ethos. **Check `web/src/components/Companion/ -grammarLite.test.ts` first** — a rules engine may already be half-built, -and there are sibling branches that look relevant and were never merged: -`feat/mechanics-deterministic-pass` ("deterministic mechanics suggestion -family, rule-based, no LLM") and `feat/calm-suggestions` ("suppress fickle -re-edits of sentences the user already settled", which reads like a -partial item 2). Read those before writing anything new. +**Suggested next:** item 3b, the instant local rules layer — but it is +**largely already built, in `main`**, and the item as written doesn't know +that. Before writing any rules engine, read: + +- `web/src/components/Companion/prose.ts` — the deterministic rules engine, + client-side, already the single source of non-LLM detection. Sibling + tests: `prose.test.ts`, `grammarLite.test.ts`. +- Commit `96f68a9` ("Add deterministic mechanics suggestion family, + rule-based, no LLM"). Applyable rules already emit exact-span + `original -> replacement` fixes that surface as suggestion cards, under + a `mechanics` family persisted via `POST /docs/{id}/mechanics`; + awareness-only rules (run-ons, splices) stay companion bubbles, and the + companion hides fix-bearing hints so a span is never both. +- Commit `9d2501a` ("Suppress fickle re-edits of sentences the user already + settled") — a partial item 2 that also already shipped. + +So item 3b's real remaining work is probably not "write the rules" but +"make the existing local hits render *immediately*, before the LLM pass, +with a modest style" — i.e. the latency/ordering half of the item, plus +whatever rules `prose.ts` is missing. Scope it against the code, not +against the item text. + +Item 5 likewise: `internal/suggestions/translate.go` already exists — read +it before designing a `translate` suggestion type. + +(An earlier draft of this handoff claimed those two commits sat on +unmerged branches. They don't; both are in `main`. That came from +misreading `git branch -vv` tracking info as merge status.) **Verification technique, for whoever picks up items 2/3/7.** Claims about editor behaviour in this doc should be checked against the running build, @@ -311,8 +330,9 @@ first through the fiber tree for an object with `.view`/`.state`/ `view.dispatch` logging `tr.docChanged` are enough to settle most "does the editor really do X" questions in a couple of minutes. -**Housekeeping:** `fix/companion-yields-to-cards` is merged and can be -deleted. Testing item 1 meant accepting suggestions on her live document; +**Housekeeping:** every topic branch in the repo was fully merged into +`main` and they have all been deleted, locally and on origin. Testing +item 1 meant accepting suggestions on her live document; the one residual edit was reverted ("on foot" → "by foots") and the doc text is as it was found, but the History panel now shows several extra auto-snapshots from that session.