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.