docs(product): native first-run product tour design record (RIG-2797) - #662
Draft
rigel-mintaka wants to merge 1 commit into
Draft
docs(product): native first-run product tour design record (RIG-2797)#662rigel-mintaka wants to merge 1 commit into
rigel-mintaka wants to merge 1 commit into
Conversation
|
Compass engineering docs preview: https://compass-ux-2797-first-run-to.compass-eng-docs.pages.dev Deployed from Changed pages: |
rigel-mintaka
force-pushed
the
compass-ux/2797-first-run-tour-design
branch
2 times, most recently
from
August 27, 2026 02:17
4c931a8 to
fa243ae
Compare
rigel-mintaka
marked this pull request as ready for review
August 27, 2026 02:18
Contributor
Author
|
✅ Unblocked — #664 merged, this PR rebased onto clean main. The main-red duplicate Ready for Matt's review + merge (the freeze) alongside the three OQ rulings on RIG-2808. |
Design record for the native first-run product tour: a store-gated App-root SolidJS overlay whose steps anchor to real chrome via data-tour attributes and drive the app's own router/store, entering on the chase-light motion primitive. No PostHog-rendered UI ships in-app; PostHog is measurement-only through a no-op-safe captureTourEvent indirection over the #656 T6 embed, and tour UI has zero dependency on that embed landing. Drafted by the design subagent, red-teamed by design-critic; both blocking findings (async anchor-resolve race, unreachable agent-workspace nav) and all should-fix findings folded. Ledger delta DL-272..275 applied to docs/designs/DECISIONS.md in the same PR (UX foundation section). Three load-bearing open questions (remote content, seen-state grain, step-arc ratification) go to Matt for ruling before the freeze. Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
force-pushed
the
compass-ux/2797-first-run-tour-design
branch
from
August 27, 2026 03:08
fa243ae to
b7990ea
Compare
rigel-mintaka
marked this pull request as draft
August 30, 2026 17:27
Contributor
Author
|
Heads up from RIG-2577 T10 (#832, now open): that PR removed the transitional This PR adds Before merge, please re-point the record to |
rigel-mintaka
added a commit
that referenced
this pull request
Sep 1, 2026
…ve-family sweep (RIG-3113) The final task (T10) of the RIG-2577 design-docs reorg. T8 dissolved `product/` into `agent/`/`server/`/`ui/`/`meta/` but left the native-app family under the transitional `product/` governed root while RIG-2542's client-only direction settled. RIG-2542 is closed (Done, 2026-08-23) and T8/T9 have merged (#825), so this empties and removes `product/`. ## What moved The 8 remaining records `product/` → `ui/` (all UI/native-shell surface): - `compass-native-app/`, `compass-native-client-mode/`, `compass-native-client-only/`, `compass-native-packaging/` - `compass-multi-window/`, `compass-stack-cross-process-teardown/`, `compass-gtk4-migration/` - `compass-tauri-shell.md` (stays flat at the `ui/` root; the corpus's only supersession pointer) ## Re-points (same PR, per CONTRIBUTING §"Moving a record is not a freeze violation") - **Ledger:** 18 `DECISIONS.md` Record cells `product/<r>` → `ui/<r>`. - **Supersession pointer:** `compass-tauri-shell.md`'s `Status: Superseded by compass-native-app/design.md` is already the final same-bucket record-relative form; verified it resolves under the generalized `resolveRecordRelative` (no `../` escape) now that both endpoints sit in `ui/`. - **Cross-bucket citations to the 8:** `infra/ci/compass-agent-image-publish`, `infra/ci/compass-dogfood-e2e`, `infra/release/compass-release-bundling`, `infra/release/compass-distribution`, `infra/runtime/compass-runner-arbitrary-uid`, plus the two moved records' own self/sibling citations. - **Code/config:** `go/e2e/client_mode_test.go`, `tools/renovate/config.json5`. ## De-govern + delete - Removed `"product"` from `GOVERNED_ROOTS` in `tools/design-ledger-gate/index.ts` (now `[ui, agent, server, meta, infra, observability, repo]`) and updated its doc comment. - Deleted the now-empty `docs/designs/product/` directory. - Dropped CONTRIBUTING §6's `product/ is transitional` subsection and the "plus the transitional `product/` root" clause; the transitional state is over. - Updated the gate's own test fixtures (`index.test.ts`) that used `product/` as a governed-bucket stand-in to `ui/` (a de-governed bucket would flip their `touchesRecord(...).toBe(true)` assertions). ## Verification - `design-ledger-gate`: OK — 284 ledger rows, 120 record headers valid, exit 0. - Gate test suite: 81 pass / 0 fail. - eng-docs `gather`: 187 docs + index + sidebar, exit 0. - Relative `.md` link resolution across all 135 design records: 0 dangling. - The ~108 remaining `docs/designs/product/...` mentions are pre-existing historical prose in frozen records (old `product/DECISIONS.md` ledger path relocated at T2, deleted `compass-0.x` version records, the old `PRODUCT_DIR` gate constant, and the separate `docs/specs/product/` tree) — none reference a moved record, and rewriting frozen records' decision prose is out of scope. ## Coordination note Two open draft PRs add new NON-native records into `product/` against the pre-T8 flat taxonomy: #601 (`compass-forge-scope-enforcement` → belongs in `server/`) and #662 (`compass-first-run-tour` → belongs in `ui/`). Both must re-point their record to the correct bucket before merge (mis-filed against the dissolved taxonomy regardless). Flagged on both PRs. Refs RIG-3113. Refs RIG-2577. Ledger-impact: 18 Record-cell path re-points (product/ → ui/); no decision rows added, flipped, or removed. Spec-impact: none. Co-authored-by: Matt Wilkinson <matt@rigel.build>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design record for the native first-run product tour: a store-gated
App-root SolidJS overlay whose steps anchor to real chrome via data-tour
attributes and drive the app's own router/store, entering on the
chase-light motion primitive. No PostHog-rendered UI ships in-app; PostHog
is measurement-only through a no-op-safe captureTourEvent indirection over
the #656 T6 embed, and tour UI has zero dependency on that embed landing.
Drafted by the design subagent, red-teamed by design-critic; both blocking
findings (async anchor-resolve race, unreachable agent-workspace nav) and
all should-fix findings folded. Ledger delta DL-265..268 applied to
docs/designs/DECISIONS.md in the same PR (UX foundation section).
Three load-bearing open questions (remote content, seen-state grain,
step-arc ratification) go to Matt for ruling before the freeze.
Co-authored-by: Matt Wilkinson matt@rigel.build