This commit is contained in:
Oleg Maslov
225
docs/ONBOARDING-INVESTIGATION-2026-04-30.md
Normal file
225
docs/ONBOARDING-INVESTIGATION-2026-04-30.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Onboarding Flow Investigation — 2026-04-30
|
||||
|
||||
**Status:** Research only. No code changed. PM friction reports FR #23-32 stay parked pending Marko's ratification on remediation path.
|
||||
|
||||
**Question:** Is the multi-step onboarding flow regressed, behind a flag, or routing to a skip-path? Where did the full flow go?
|
||||
|
||||
**Answer (one sentence):** The 8-step flow is healthy on `main`, fully implemented, and is the documented canonical UX — PM didn't see it because the fresh-state reset preserved the workspace shell directory, and `useOnboarding.ts` auto-completes the wizard whenever `/api/workspaces` returns ≥ 1 workspace.
|
||||
|
||||
---
|
||||
|
||||
## 1. The full flow exists and is documented
|
||||
|
||||
**Step files (all present in `apps/web/src/components/os/overlays/onboarding/`):**
|
||||
|
||||
```
|
||||
WelcomeStep.tsx ApiKeyStep.tsx
|
||||
WhyWaggleStep.tsx ModelTierStep.tsx
|
||||
TierStep.tsx TierStep.tsx
|
||||
ImportStep.tsx ReadyStep.tsx
|
||||
TemplateStep.tsx PersonaStep.tsx
|
||||
```
|
||||
|
||||
**Step order** — `OnboardingWizard.tsx:34`:
|
||||
```ts
|
||||
const STEP_NAMES = ['welcome', 'why-waggle', 'tier', 'memory-import',
|
||||
'template', 'persona', 'api-key', 'ready'];
|
||||
```
|
||||
|
||||
**Documented in** (no ambiguity — Marko's mental model matches code):
|
||||
- `docs/UX-ASSESSMENT-2026-04-16.md:36` — *"8-step full-screen wizard: Welcome (auto-advance 3s) → Why Waggle (value props) → Tier selection → Memory Import → Template selection (15 templates) → Persona selection (19 personas) → API Key entry → Ready (auto-advance 2s)."*
|
||||
- `docs/product-analysis/FOUNDER-REVIEW.md:90` — *"Onboarding wizard: 8 steps. Best case (skip everything): ~5 seconds. Typical: 2-3 minutes."*
|
||||
- `docs/product-analysis/FOUNDER-REVIEW.md:225` — recommends *"Reduce onboarding from 8 steps to 5"* (recommendation, not implemented).
|
||||
- `docs/plans/HARVEST-AUDIT-2026-04-20.md:106` — references the wizard flow being amenable to "harvest-first onboarding" reordering.
|
||||
|
||||
**Each step covers what Marko remembered:**
|
||||
- **WhyWaggleStep**: value props ("intermediate guidance messages")
|
||||
- **ImportStep**: memory upload from ChatGPT / Claude / Gemini / Perplexity / Cursor / Claude Code (Marko's memory upload step)
|
||||
- **TemplateStep**: workspace template selection (15 templates — sales-pipeline, research-project, code-review, etc.) — this is Marko's "workspace definition" with auto-naming from template name
|
||||
- **PersonaStep**: persona picker (19 personas) — Marko's "user choice, not auto-Researcher"
|
||||
|
||||
---
|
||||
|
||||
## 2. Why PM didn't see it — the auto-complete branch
|
||||
|
||||
**Source:** `apps/web/src/hooks/useOnboarding.ts:77-106`
|
||||
|
||||
```ts
|
||||
useEffect(() => {
|
||||
if (state.completed) return;
|
||||
let cancelled = false;
|
||||
(async () => {
|
||||
try {
|
||||
const workspaces = await adapter.getWorkspaces();
|
||||
if (cancelled) return;
|
||||
if (Array.isArray(workspaces) && workspaces.length > 0) {
|
||||
console.info(`[useOnboarding] returning user detected (${workspaces.length} workspaces on server) — auto-completing wizard`);
|
||||
const next: OnboardingState = {
|
||||
...defaultState,
|
||||
completed: true,
|
||||
step: 7,
|
||||
tier: state.tier || 'power',
|
||||
tooltipsDismissed: true,
|
||||
apiKeySet: true,
|
||||
};
|
||||
saveState(next);
|
||||
setState(next);
|
||||
}
|
||||
} catch { /* sidecar unreachable — stay on wizard */ }
|
||||
})();
|
||||
return () => { cancelled = true; };
|
||||
}, []);
|
||||
```
|
||||
|
||||
**What this does:** on hook mount, if `state.completed === false`, calls `/api/workspaces`. If the response array has any length, flips `state.completed = true, step = 7` (final step) and persists to localStorage.
|
||||
|
||||
**Why it fired for PM's "fresh state":** the reset I executed (per Marko's ratified plan) preserved `~/.waggle/workspaces/default-workspace/workspace.json`. The backend's WorkspaceManager loads workspace metadata from that file on boot, so `/api/workspaces` returned 1 workspace. The hook auto-completed → `<OnboardingWizard>` was never rendered (gated by `!onboardingState.completed` in `Desktop.tsx:462`).
|
||||
|
||||
**What PM saw instead:**
|
||||
1. **Boot** → service health probe + adapter.connect()
|
||||
2. **Welcome modal "Default Workspace"** — this is `LoginBriefing.tsx`, not OnboardingWizard. LoginBriefing renders **after** onboarding completes; it's the "Welcome back, here's your memory" panel for returning users. Triggered by `Desktop.tsx:472` `{onboardingState.completed && ov.showLoginBriefing && (...)}`.
|
||||
3. **Hero screen** — the bare desktop with dock + status bar + "Click an app in the dock" hint.
|
||||
4. **Chat with starter prompts** — clicking the dock chat icon opens an empty chat window.
|
||||
|
||||
So PM correctly observed the post-completion experience — the wizard branch was bypassed entirely.
|
||||
|
||||
---
|
||||
|
||||
## 3. Git archaeology
|
||||
|
||||
### `04add13` — auto-complete behavior introduced
|
||||
|
||||
```
|
||||
Author: Marko Markovic <marko.markovic@egzakta.com>
|
||||
Date: Sun Apr 12 00:15:01 2026 +0200
|
||||
Subject: fix(onboarding): skip wizard for returning users + vault pre-check + name propagation
|
||||
|
||||
Bug #2 — Wizard re-shown for returning users.
|
||||
The wizard's gating was purely localStorage-based, so a fresh
|
||||
Tauri webview (or a browser-profile switch) always looked "new"
|
||||
even when the sidecar already had the user's memory, workspaces,
|
||||
and vault. useOnboarding now issues a one-shot query to
|
||||
/api/workspaces on mount; if any workspace is returned, the user
|
||||
is flagged completed with tier=power and tooltipsDismissed=true.
|
||||
Sidecar-unreachable keeps the wizard visible so genuine first-run
|
||||
still works.
|
||||
```
|
||||
|
||||
**Verdict:** intentional fix authored by Marko. Not a regression. The behavior is correct for the documented use case (Tauri webview switch with real existing data on the sidecar).
|
||||
|
||||
### `bd1f1f1` — Tauri filesystem flag (NOT on main)
|
||||
|
||||
```
|
||||
Author: Marko Markovic <marko.markovic@egzakta.com>
|
||||
Date: Wed Apr 29 23:19:46 2026 +0200
|
||||
Subject: feat(sesija-a/A11): wire useOnboarding to Tauri first-launch flag
|
||||
Branch: feature/apps-web-integration ← not merged to main
|
||||
```
|
||||
|
||||
This commit added a complementary Tauri-side filesystem flag (`~/.waggle/first-launch.flag`) so onboarding state survives WebView profile resets in Tauri mode. Lives only on `feature/apps-web-integration`. **Irrelevant to PM's main-branch test** — the current main has only the workspaces-check.
|
||||
|
||||
### Other recent onboarding commits on main (Apr 12 - Apr 29)
|
||||
|
||||
```
|
||||
1b40a51 feat(web): M-10 — onboarding tile expansion + Claude Code auto-detect
|
||||
4031035 fix(web): P1 — forward personaId from onboarding finish to first chat window
|
||||
792755f feat(web): P17.4 — Overlays + onboarding title= → HintTooltip
|
||||
cf1ec6e feat(web): L-02 + L-04 — responsive StatusBar + onboarding template grid
|
||||
304b231 feat(web): M-18 · UX-1 — "Skip and set me up" shortcut on WhyWaggle step
|
||||
8782cab feat(web): Phase A/B polish — spawn-agent empty states + theme-aware logo
|
||||
70c8d84 feat(web): QW-5 — rename dock tiers + clarify vs billing
|
||||
47539ac feat(web): QW-4 — Back button on onboarding steps 2-6
|
||||
9a4ddbe feat(onboarding): custom OR model input + OpenRouter fallback routing
|
||||
2dc8f93 feat(onboarding): 3-tier model picker with free-first default
|
||||
9776109 fix(ux): explicit Continue button on WelcomeStep (WCAG 2.2.1)
|
||||
a5f6968 fix(ux): WCAG 2.1 AA pass on PersonaSwitcher + OnboardingWizard shells
|
||||
77c188e feat(onboarding): expand to 15 templates, 22-persona system
|
||||
7c45176 fix(web): show workspace creation error in onboarding instead of silent local fallback
|
||||
```
|
||||
|
||||
All of these are **enhancements** to the existing 8-step flow. None remove steps or short-circuit the wizard. The flow has been actively maintained, not regressed.
|
||||
|
||||
---
|
||||
|
||||
## 4. Remediation options for PM walkthrough
|
||||
|
||||
The flow code is fine. The issue is purely "how do we get the wizard to render for testing".
|
||||
|
||||
### Option A — Deeper reset (recommended for PM walkthrough)
|
||||
|
||||
Add to the wipe step:
|
||||
```bash
|
||||
rm -rf ~/.waggle/workspaces/default-workspace
|
||||
```
|
||||
|
||||
After this, `/api/workspaces` returns an empty array (or just a placeholder). The auto-complete branch's `workspaces.length > 0` evaluates false, the wizard renders. PM gets the true 8-step flow.
|
||||
|
||||
**Side effect:** the backend may regenerate `default-workspace` on first interaction (workspace creation is part of the wizard's `handleFinish` path). Walkthrough should still work end-to-end. The new workspace gets the user's chosen template + persona + name.
|
||||
|
||||
**Implementation:** when PM signals readiness, I can:
|
||||
1. Stop backend.
|
||||
2. `rm -rf ~/.waggle/workspaces/default-workspace`.
|
||||
3. Restart backend with `WAGGLE_PROMPT_ASSEMBLER=1`.
|
||||
4. Verify `/api/workspaces` returns empty / placeholder-only.
|
||||
5. PM clears localStorage + reloads → wizard renders.
|
||||
|
||||
This preserves the rest of the prior reset (no memories, no other workspaces, vault keys intact).
|
||||
|
||||
### Option B — Force-render flag for testing (code change, scope creep)
|
||||
|
||||
Add a `?forceWizard=true` URL param to `useOnboarding.ts` that bypasses the workspaces check. Symmetric with the existing `?skipOnboarding=true` E2E bypass at line 27.
|
||||
|
||||
Cost: small code change (~10 LOC), needs typecheck + commit + push. Marginal benefit over Option A. **Not recommended unless PM repeats this fresh-state test often.**
|
||||
|
||||
### Option C — Ratify the current 4-surface flow as Day 0 UX
|
||||
|
||||
If Marko/PM decide the 8-step flow is too long for Day 0 launch (founder review explicitly recommended reducing to 5 steps), the current "Welcome modal + Hero + Chat" auto-advance path could be ratified as the intentional shipped UX. Then the wizard becomes a **secondary** flow accessed via a hypothetical "Reset onboarding" affordance in Settings.
|
||||
|
||||
This is a **product decision**, not a code question. Out of scope for this investigation.
|
||||
|
||||
---
|
||||
|
||||
## 5. Findings summary table
|
||||
|
||||
| Question | Answer |
|
||||
|---|---|
|
||||
| Does the multi-step flow exist in code? | **Yes** — 8 steps, fully implemented, enhanced as recently as 2026-04-26. |
|
||||
| Does it cover Marko's remembered steps (workspace def + persona picker + memory upload + intermediate guidance)? | **Yes** — TemplateStep + PersonaStep + ImportStep + WhyWaggleStep cover all four. |
|
||||
| Is it documented as the canonical Day 0 UX? | **Yes** — `UX-ASSESSMENT-2026-04-16.md` and `FOUNDER-REVIEW.md` both describe the 8-step flow as the current state. |
|
||||
| Is it behind a feature flag? | **No** — no `WAGGLE_*` env var or feature flag gates it. |
|
||||
| Why didn't PM see it on the fresh-state walkthrough? | **`useOnboarding.ts:77-106`** auto-completes the wizard whenever `/api/workspaces` returns ≥ 1 workspace. The reset preserved `default-workspace/workspace.json`, so the backend reported 1 workspace, auto-complete fired, wizard never rendered. |
|
||||
| Is this a regression? | **No** — the auto-complete behavior is intentional (commit `04add13`, 2026-04-12, fixes Bug #2 "wizard re-shown for returning users on Tauri webview switch"). |
|
||||
| Recommended remediation? | **Option A**: `rm -rf ~/.waggle/workspaces/default-workspace` and restart. Simplest, no code change, preserves the rest of the reset. |
|
||||
|
||||
---
|
||||
|
||||
## 6. PM friction reports FR #23-32 — what they're for
|
||||
|
||||
PM's friction reports were written against the **truncated 4-surface flow** PM actually saw. After Option A unblocks the full 8-step wizard, those friction reports may need re-triage:
|
||||
|
||||
- Some FR's may be valid for the post-onboarding state (LoginBriefing, Hero, dock, chat) regardless of which onboarding flow was used → still valid, ship-as-is.
|
||||
- Some FR's may be specific to the truncated flow's UX gaps (e.g., "no persona picker offered") → moot once the wizard renders.
|
||||
- Some FR's may surface NEW bugs in the wizard itself (Welcome → WhyWaggle → Tier → Import → ... transitions) → the **reason** to re-trigger the wizard for a proper test.
|
||||
|
||||
**Recommendation:** before fix-batching FR #23-32, run the deeper reset (Option A) and have PM re-walkthrough. Re-triage the friction reports against the 8-step flow.
|
||||
|
||||
---
|
||||
|
||||
## 7. Out-of-scope notes
|
||||
|
||||
- The `bd1f1f1` Tauri filesystem flag is on `feature/apps-web-integration`, not main. If/when that branch merges, the auto-complete logic gets a second trigger (Tauri-side flag) — same gating, more durable. Doesn't affect main.
|
||||
- The founder review's "reduce to 5 steps" recommendation has not been implemented. If Marko wants to act on that for Day 0 launch, that's a separate scope.
|
||||
- I did not modify any code or run any commands during this investigation — strictly research per the brief.
|
||||
|
||||
---
|
||||
|
||||
**File references:**
|
||||
- `apps/web/src/hooks/useOnboarding.ts:77-106` — the auto-complete branch
|
||||
- `apps/web/src/components/os/overlays/OnboardingWizard.tsx:34` — `STEP_NAMES`
|
||||
- `apps/web/src/components/os/overlays/onboarding/*.tsx` — 9 step component files
|
||||
- `apps/web/src/components/os/Desktop.tsx:462-464` — wizard mount conditional
|
||||
- `apps/web/src/components/os/overlays/LoginBriefing.tsx` — what PM mistook for the welcome step
|
||||
- `docs/UX-ASSESSMENT-2026-04-16.md:36` — canonical 8-step flow description
|
||||
- `docs/product-analysis/FOUNDER-REVIEW.md:90, 225` — flow described + reduction recommendation
|
||||
- Commit `04add13` (2026-04-12) — auto-complete-for-returning-users fix
|
||||
- Commit `bd1f1f1` (2026-04-29, on `feature/apps-web-integration`) — Tauri flag addition (NOT on main)
|
||||
Reference in New Issue
Block a user