Progressive onboarding path
I wrote this to plan how TuckBuddy would teach itself over time, revealing each feature at the moment it helps instead of front-loading an intro.
What happened next: The ask-in-context rules carried into the 1.0 onboarding. A later activation doc updated this plan to match what shipped.
A living growth & onboarding system for HomeBase. The philosophy is based on my own progressive-onboarding work (chromatic.net — "Asking Less to Get More"): a trust-gated activation system that asks only in exchange for value, governed so prompts never become noise. This doc applies it to HomeBase and is meant to be updated every time a feature ships — slot the new feature into the tiers, define its reveal trigger, and wire its interrelations (see the rubric below).
Build status. The keeper first-run flow (Layer 1) from the storyboard is shipped. It is a conversational five-step flow with a growing breadcrumb dock, in Tuck Buddy's voice, on the neutral frosted surface, with question lines in New York serif, a real first item and a cascade finale. The signals layer ships as a stub. The rest of this doc (the coach engine, the reveal table, milestones, win-back) is open backlog work.
0 · The governing principles (every reveal obeys these)
Distilled from the case study + my stated intent:
- Only ask/reveal when you're giving something back. Never a cold ask. The data collection doesn't change; the user's reason to say yes does.
- Ask in context, anchored to a moment of value — never up front. The same ask converted ~2× (savings) to ~7× (push) higher placed after value vs. cold at signup, and selected for users who actually used what they signed up for. Volume can fall; channel quality rises.
- Optimize for capability & mental model, not funnel completion. A flow tuned for completion produces "compliant users, not capable ones," and the mental model decays. Give the right info at the right time so the model sticks.
- Value before authentication; value before payment. Auth and payment are invasive; earn them. Let the user get real value first, then a taste of premium, before any gate.
- Soft proxy before any one-shot / invasive ask. iOS lets you invoke a permission once; after a decline the conversation is over. Use an in-app soft prompt anchored to a moment the user already cares about, and preserve the single real OS prompt for the high-intent moment. (Applies to notifications, camera, and account sign-in.)
- Govern the noise — one owner of the total ask budget. The old flow accumulated asks that were each "locally defensible, none accountable for the total." This doc is that owner. Rules: never the same prompt twice running, spread reveals out, at most one new thing per session, and don't prompt after every celebration.
- Repetition → shortcut is the exception. If the user does the same thing over and over and a feature is a genuine shortcut, make sure they learn it — this reveal may fire even inside a cooldown, because the user is signalling the pain themselves. Still: once.
- Never promote what the user will fail at. Surfacing a feature they're not ready for "teaches users to associate the app with the word no." Gate reveals behind a readiness signal.
- The interface grows up around the user. Capability-aware surfaces: reveal advanced UI as mastery shows, rather than exposing everything on day one (features "plainly visible on screen failed to register as available" — presence isn't activation).
- Celebrations delight but never block the habit. Especially in a mass-entry app that should reward repetition — a celebration must never interrupt the flow of continuing to add.
- Surface data-management as data accumulates — organization and backup appear when the pile makes them matter, not before.
- Welcome the user back after a mindful absence with their past success, before any ask.
- Measure activation, not vanity. Research once made the old problem look smaller than it was (survey scores were fine; real-task behavior wasn't). Track whether a capability is used, not just seen.
1 · Capability tiers (the map — HomeBase adapted from the case study's 4-tier model)
| Tier | Case-study analog | HomeBase | Gate |
|---|---|---|---|
| T0 — Always on | Account safety & compliance (can't skip) | Open app · create a home/zone · add an item manually · see it saved | None — no auth, no permission, no payment. This is the "small value before you authenticate." |
| T1 — Core behaviors | Unlocked by behavior + time | Photos · categories · tags · search · multiple zones · item detail · Unsorted | Earned by doing — surfaced as the user's data makes them useful |
| T2 — Contextual extensions | Surfaced only when situationally relevant | Scan a book · Describe It / Add Several · Lists · manual sort/reorder · filters · backup/export · Unsorted cleanup | A relevance signal (see the reveal table) — never before it applies |
| T3 — Advanced / premium | Only when the signal is strong | AI features (consent + credits/subscription) · CloudKit sync · multi-user sharing | A strong readiness signal + a taste first; auth/payment only here |
The user climbs by using the app, not by being told. Each tier's features are revealed at their moment (see the reveal table), not dumped in an intro.
2 · Reveal moments (trigger → anchor → reveal)
The heart of the system. Each row = a usage signal, the value moment it anchors to, and what's revealed. All obey the governance rules.
| Trigger signal | Anchor (value moment) | Reveal | Tier | Notes |
|---|---|---|---|---|
| 1st item saved | The save celebration | Nothing new. Let them repeat and feel fluent. | — | Never teach on the very first success. |
| ~5–8 items added one-by-one, manually | Right after another save | "Adding a lot? Add Several or Describe It can do a batch." | T2 (shortcut) | The repetition→shortcut rule. May fire under cooldown. Once. |
| Added an item with category = Books | After the book saves | "Next time, scan the barcode — it fills in the cover and details." | T2 | Only when it applies; once. |
| 2+ zones or ~15+ items | On returning to Home | "Your collection's growing — Search and browse-by-category find things fast." | T1 | Anchored to the moment finding gets non-trivial. |
| Unsorted count crosses ~10 | On opening Unsorted / Home | "You have N unsorted items — tuck them into locations." | T1 + data-mgmt | Organization surfaced when the pile makes it matter. |
| Library crosses ~25 items | A milestone celebration | "That's a real collection. Back it up in Settings." | T2 (data-mgmt) | Ties backup to the point where loss would hurt. |
| Several similar items (same tag/category) or a trip/donate-shaped context | After tagging/saving | "Group these into a List — a packing list, a donate pile." | T2 | Introduce Lists only when there's something worth grouping. |
| A collection grows past ~20 and is browsed repeatedly | In that collection | "Reorder by hand with Manual sort, or filter to narrow it." | T2 | Advanced UI grows in as the collection matures. |
| User attempts / would benefit from AI entry | At the point of entry | Taste: run 1–2 Describe It parses free → then the consent + credits gate. | T3 | Value before the gate; the AI consent step is the trust step. |
| A second device or partner appears (or a big library) | A "protect this" moment | Soft-proxy the benefit of sync/sharing ("keep this on your iPad / share with your partner") before the real sign-in. | T3 | Preserve the single real auth prompt for high intent. |
| Return after a mindful absence (~14+ days) | App open | "Welcome back — X items across Y locations, Z books catalogued." Then maybe one highly-relevant next step. | — | Celebrate first; ask second, if at all. |
(Thresholds are starting guesses. Tune them against real activation data, and add new rows as features ship, using the rubric.)
3 · The trust & value ladder (auth + premium)
HomeBase is local-first, which is a gift here — the entire core inventory works with zero account, so T0–T2 deliver deep value before any invasive ask. Sequence:
- Local value first — capture, organize, search, back up: all no-account. (Most apps can't do this; HomeBase can.)
- Taste of premium — let the user feel the AI magic (a couple of free parses) before the gate. Never gate what they haven't tasted.
- Consent as the trust step — the AI data-sharing consent: explicit, in-context, default-off, framed as "what leaves your device, and why." Trust earns the yes.
- Auth only when it buys something — sync across devices / share with a partner. Soft-proxy the benefit at a real moment (new device, or a library big enough to protect) before the real sign-in.
- Payment last, tasted first — AI credits or a subscription, introduced after the value is felt and the cost to me (the API) is real. Never cold.
4 · Governance (the anti-noise engine — the part most apps skip)
One place owns the total prompt budget. Rules:
- One new thing per session, max. Never introduce two unfamiliar features in a sitting.
- Global cooldown between reveals — measured in sessions and days (e.g., ≥ 3 sessions or ≥ several days), so a heavy-entry binge doesn't trigger a parade.
- Show once. A dismissed reveal doesn't return — or returns only after a long, meaningful gap with a different anchor (the notification-proxy pattern).
- Decouple celebration from teaching. Celebrate freely; attach a next-step to only some celebrations, and never two sessions running.
- Repetition override is the one exception to the cooldown — high-value, user-signalled — but still fires once.
- Readiness gate — never reveal a feature the user can't yet succeed at (no sync with one device; no Lists with three items).
- Never block the flow — a reveal is dismissible in one tap and never sits between the user and the next add.
5 · Celebration design
Celebrations are a delight and the best place to introduce a related, unexplored feature, but they are rationed by the governance rules. A tiered cadence:
- Micro (every save): the existing toast + success haptic. No teaching. Pure reinforcement of the habit.
- Milestone (1st item, 10th, 25th, 100th; first book scanned; first list; first backup): a richer moment (a bigger toast / a tasteful flourish). Some milestones carry one next-step reveal, per the governance rules.
- Return: a warm past-success summary.
Milestones are where a mass-entry app rewards you for the grind — they should feel earned, never nag.
6 · Data-management, surfaced as you go
Per the data-management principle, the tools to manage data appear as the data appears, mapped to the reveals above: Search/browse, Unsorted cleanup, Backup/export, Tags & Lists, Manual sort & filters, and later Sync. The principle: the user should always be able to see the next handle on their growing collection, right when the collection makes that handle useful.
7 · The living-doc rubric — how to slot a NEW feature
When a feature ships, add it here by answering six questions:
- Tier? T0 / T1 / T2 / T3.
- Value anchor? The exact moment of value it should ride in on.
- Readiness signal? What proves the user is ready to succeed at it (not just be shown it)?
- Interrelations? What existing feature(s) does it come after / pair with? (Add it to the map below.)
- Celebration? Does its first successful use warrant a milestone?
- Governance? Once / cooldown / shortcut-override / readiness gate.
Feature interrelation map (after X, consider Y)
- Manual add ➜ (repeat) ➜ Add Several / Describe It
- Add a book ➜ Scan a book ➜ Bookshelf views
- Items pile up ➜ Search ➜ Filters
- Similar items / a purpose ➜ Lists ➜ Add-to-list from multi-select
- Unsorted grows ➜ Move / organize into zones
- A big collection ➜ Manual sort · Backup/export
- Real data worth protecting ➜ Sync ➜ Sharing / multi-user
- Heavy entry ➜ AI (taste) ➜ Consent ➜ Credits/subscription
Keep this map current — it's the "what's naturally next" that powers contextual reveals.
8 · How I'd build this in HomeBase (implementation sketch)
Concrete, mapped to the existing codebase. This is a system, not scattered prompts — one engine, one policy, one budget.
A. A local signals layer. A small store of usage counters/flags — items added (and by method: manual / scan / photo / AI), consecutive manual adds, per-category counts, zones count, unsorted count, lists count, sessions, last-open date, backups run, and a per-reveal seen/dismissed set. It is cheap to build: simple on-device settings storage for scalars and flags, or a tiny observable signals store written on the existing save paths (the item form, quick add, scan, import). This doubles as the analytics source (log the same events to TelemetryDeck/PostHog), so one instrumentation pass has two payoffs.
B. A coach / nudge engine (the governance owner). One onboarding coach that, at defined checkpoints, evaluates the reveal table against the signals and the governance policy and returns at most one reveal, or nothing. It holds the cooldown, the one-per-session cap, the seen/dismissed set, and the repetition-override and readiness gates. Everything about "should we say something right now?" lives here, so there's a single throttle instead of prompts sprinkled across screens (exactly the "no owner of the total" failure the case study names).
C. Celebration hooks on existing success points. The app already has a toast and a success haptic on saves. Extend with milestone detection (counts crossing thresholds) → a richer celebration, and ask the coach whether this milestone carries a next-step. Micro-celebrations stay pure (no teaching).
D. Reveal surface = the unified explainer. The backlog's "one shared explainer interface" is the delivery mechanism: a single tasteful, one-tap-dismiss card the coach populates. Building the explainer and the coach together means every reveal looks consistent and is centrally governed.
E. Repetition→shortcut detector. Track the consecutive-manual-add streak in the signals; when it crosses the threshold, the coach may surface the Add-Several/Describe-It reveal even under cooldown (the one override).
F. Capability-aware surfaces (interface grows up). Gate the visibility/prominence of advanced affordances on signals — e.g. Manual sort, filters, and Lists entry points stay quiet until their readiness signal, then appear. It stays small and reversible: a computed show-or-hide check per affordance reads the signals and defaults to visible for anyone past the threshold, so it never hides something a returning power user expects.
G. Win-back. On launch, if the last open was ~14 or more days ago, show the past-success summary (all data the signals already hold) before anything else; the coach may attach one high-relevance next step.
H. Gating & taste (T3). AI: allow N free parses (a counter), then the consent gate → the credits/subscription gate (StoreKit), all in-context at the point of use, never cold. Sync/sharing: soft-proxy card before the real sign-in.
Backlog shape: This is filed as the Growth & Onboarding epic in the backlog. It sequences the AI consent gate Built, the explainer surface, and analytics/signals; the keeper flow (Layer 1) now covers most of the old first-run onboarding item. The signals layer shipped as a stub with the onboarding writes wired. The next slice is the coach engine plus the first reveal (the repetition shortcut), delivered through the explainer surface. It is the highest-value, most-testable proof, and it rides the instrumentation I'll want for analytics anyway. The remaining signals work is instrumenting the real add paths so the coach has live signals to read.
9 · Open questions to tune with data
- Exact thresholds (the repetition streak and the item-count triggers) — start with the guesses above, tune against activation.
- Which milestones carry a next-step vs. celebrate-only.
- Cooldown length in sessions vs. days for a mass-entry app (bingers vs. daily dippers behave very differently).
- Win-back absence window (14 days? tied to their entry cadence?).