TenantAtlas/specs/121-workspace-switch-fix/research.md

Research: Workspace Switch Semantic Fix

Feature: 121-workspace-switch-fix | Date: 2026-03-07

R1: Canonical destination for intentional workspace switching

Decision: Use ChooseWorkspace::getUrl(panel: 'admin').'?choose=1' as the context-bar target for Switch workspace.

Rationale: The codebase already treats the chooser page as the canonical manual-switch experience. The admin user menu uses this exact destination today, while the context bar still points to the workspace CRUD index. The ?choose=1 parameter is the established convention for bypassing workspace auto-resume and forcing the chooser when the user explicitly intends to switch.

Alternatives considered:

• Link to route('filament.admin.resources.workspaces.index'): rejected because that is the management surface (Manage workspaces), not the switch flow.
• Link to /admin/choose-workspace without ?choose=1: rejected because the codebase already documents ?choose=1 as the explicit forced-chooser contract for intentional switching.

R2: Post-selection redirect behavior after entering the chooser

Decision: Preserve the chooser’s existing redirect behavior after a workspace is selected.

Rationale: ChooseWorkspace::selectWorkspace() already resolves post-selection flow through WorkspaceIntendedUrl::consume() and WorkspaceRedirectResolver::resolve(). That behavior is covered by existing tests and is outside this spec’s scope. The fix is semantic routing into the chooser, not a redesign of what happens after a user selects a workspace.

Alternatives considered:

• Always redirect back to the current page after selection: rejected because it would change established chooser behavior and broaden scope beyond a low-risk semantic correction.
• Always redirect to one fixed landing page: rejected because it would bypass the existing tenant-count branching contract.

R3: Separation between switching and management

Decision: Keep workspace management reachable only through its existing dedicated administrative destinations, while the context bar becomes chooser-only.

Rationale: The chooser page already exposes a capability-aware Manage workspaces link for eligible roles, and the workspace resource itself is explicitly labeled Manage workspaces. This preserves the intended split between operational context switching and workspace CRUD administration.

Alternatives considered:

• Add both switch and management links to the same context-bar action surface: rejected because it would continue the semantic conflation the spec is correcting.
• Hide workspace management entirely from chooser-adjacent flows: rejected because the current dedicated management affordances are valid and already capability-aware.

R4: Smallest reliable test strategy

Decision: Extend response-level topbar rendering coverage in HeaderContextBarTest, and rely on existing workspace chooser/navigation tests for regression protection around management and forced chooser behavior.

Rationale: The bug lives in a rendered Blade partial in the admin topbar, so the most direct regression test is an HTTP response assertion on a real admin page that includes the context bar. Existing tests already cover chooser routing semantics, forced chooser behavior, chooser management-link visibility, and navigation hub separation.

Alternatives considered:

• Test only the chooser Livewire page: rejected because it would not assert the actual broken context-bar link.
• Add browser-only coverage: rejected because existing response-based feature tests already cover the required semantic contract at lower cost.