ADR-0038: Onboarding Content Strategy — Full Tour with Path Selection

Context

• The onboarding flow (ADR-0034) has ~10 screens to introduce users to LocusFlow's value proposition.
• Two core paradigms power the app: GTD (capture → process → act) and Reflection (daily reflection → weekly synthesis → personal vision).
• Users cannot be assumed to know GTD. The onboarding must teach enough for users to understand why they should capture items and how processing works.
• The app also offers a personal vision and reflection system that serves a different user need (self-awareness and alignment) from GTD's task management focus.
• Both feature sets deserve thorough explanation, but presenting everything on first run risks information overload.
• No sample data is provided (ADR-0036); explanatory content is the sole teaching mechanism during onboarding.

Constraints:

• ~10 screens total (ADR-0034) — the four concept screens (screens 4–7) carry most of the educational content; setup screens (1–3, 8) are functional, not explanatory.
• The four concept screens for each path must be reusable verbatim in the Tutorials section (accessible from Settings), independent of onboarding state.
• Must work for GTD novices, not just productivity-system enthusiasts.
• Visual design (exact diagrams, copy, illustrations) is out of scope for this ADR.

Decision

1. Complete Tour, Not Progressive Disclosure

We will provide a complete tour of the selected onboarding path — not progressive disclosure that unlocks features over time.

Each explanatory screen fully describes the concepts it covers. There are no "you'll learn this later" deferrals, no drip-fed feature unlocks, and no "day 2" follow-up prompts. After onboarding, the user has access to all enabled features immediately.

2. Onboarding Path Selection: GTD-First or Vision-First

The onboarding offers two conceptual paths. The user selects their starting path on the Path Selection screen (screen 3), after completing the non-skippable name and timezone setup:

For the initial implementation, only the GTD-first path will be built. The Vision-first path is defined here architecturally but deferred until the Personal Vision feature (Phase 12) is implemented.

When only one path is available, the Path Selection screen is skipped and the GTD-first path runs automatically. When both are available, the Path Selection screen presents the choice and the user can always access the other path later via Settings → Tutorials.

3. Full Screen Sequence

The full onboarding sequence, with content scope for each screen:

4. GTD-First Concept Screens (Screens 4–7)

Each concept screen includes:

• A single core idea (one concept per screen, not a wall of text).
• A simple diagram or annotated illustration that visually conveys the workflow (e.g., a capture-to-inbox arrow diagram, a processing decision tree).
• A brief tagline (1–2 sentences) summarizing the concept.
• Optional "Learn more" expandable for users who want deeper explanation without cluttering the default view.

5. Vision-First Concept Screens (Screens 4–7, Deferred to Phase 12)

When implemented, the Vision-first concept screens focus on self-awareness and alignment before introducing execution tools:

Both paths cover the same app features — GTD, reflection, and AI — but with different entry points and emphasis. Once both paths are available, the path not chosen during onboarding is accessible at any time from Settings → Tutorials.

6. Tutorial Reuse of Concept Screens

The eight concept screens (four GTD + four Vision) are the primary educational content of the app. They are designed to be reused verbatim in the Tutorials section of Settings:

• Each concept screen composable is fully stateless (ADR-0034 §5) with no dependency on onboarding-specific state or ViewModels.
• The Tutorials section presents the same composables through a tutorials/ nested NavGraph with a TutorialsViewModel that supplies callbacks with onSkip = null and makes no DataStore writes.
• GTD concept screens and Vision concept screens are available as independent tutorial groups — the user can replay either path without replaying both.
• This reuse is the primary reason concept screen composables live in gtd/ and vision/ sub-packages rather than a monolithic onboarding package (ADR-0034 §2).

7. Content Depth: Sufficient for Novices

All explanatory content is written for users who have never heard of GTD:

• No jargon without definition (e.g., "Next Action" is defined on first use, not assumed).
• Diagrams use plain language ("What should I do with this?" not "Processing Decision Tree").
• The reflection concept is introduced as "daily check-in" before using the word "reflection."
• Concepts are ordered from concrete (capture a thought) to abstract (reflection, vision).

8. Content Format: Static Composables

Onboarding content is implemented as static Compose layouts — not loaded from assets, not fetched from a server, not rendered from Markdown at runtime.

This means:

• Content is hardcoded in composable functions (text, Image, Canvas-based diagrams).
• Content updates require a code change and app release.
• No runtime content loading, no asset parsing, no WebView.

This is appropriate for a pre-release app where content will iterate based on tester feedback and where the overhead of a content management system is not justified.

Rationale

• Complete tour over progressive disclosure. Progressive disclosure (unlock features over time) works well for complex SaaS products with multi-session onboarding. LocusFlow is a local app with a single onboarding session. Teaching everything upfront and letting the user explore at their own pace is simpler and more respectful of the user's autonomy.
• Path selection acknowledges that different users come to LocusFlow for different reasons. Some want task management (GTD), others want self-reflection (vision). Both are valid entry points. The architecture supports both paths with separate concept screen sets; shared setup screens (Welcome, Timezone, AI Opt-In, Ready) are path-agnostic.
• GTD-first as initial implementation reflects that GTD features (inbox, processing, next actions) are more fully implemented than Personal Vision (Phase 12). Teaching what exists is more useful than teasing what's coming.
• Static composables over dynamic content is a conscious trade-off: no parsing overhead, no rendering edge cases, full Compose Preview support, at the cost of requiring a code release to update copy. Acceptable for pre-release.
• Novice-friendly copy is essential. GTD has decades of jargon ("mind like water," "natural planning model") that means nothing to new users. Plain language first, GTD terminology second.

Consequences

• Positive:
  • Users get a focused, path-appropriate 4-screen introduction to their preferred paradigm.
  • No complex unlock-over-time state machine needed.
  • Concept screens are reused verbatim in Tutorials — zero content duplication.
  • Path selection future-proofs the architecture; Vision screens are defined now.
  • Static composables are trivial to test (ADR-0026 Tier 2) and preview.
• Negative:
  • 8 concept composables (4 GTD + 4 Vision) is a meaningful content authoring effort.
  • Vision-first path is deferred, so path selection UI is not in the initial release.
  • Content quality (diagram clarity, novice-friendly copy) is critical; poor execution cannot be compensated by good architecture.
  • Content changes require app releases (acceptable for pre-release).
• Follow-up:
  • Detailed copy and diagram design will be specified in a UI/UX document, not this ADR.
  • When Personal Vision (Phase 12) ships, the Vision-first screens should be completed and the Path Selection screen enabled.
  • User testing should validate whether 4 concept screens per path is the right depth for GTD novices. The architecture accommodates adding or merging screens.

Alternatives Considered

• Progressive disclosure (feature drip) — rejected. Requires tracking which features have been unlocked, scheduling follow-up prompts, and deciding when to reveal each feature. This complexity is not justified for a ~6-screen onboarding in a pre-release app.
• Single linear tour (no path selection) — rejected architecturally. While the initial implementation is GTD-first only (effectively linear), designing the architecture with path selection from the start avoids a refactor when Vision is ready.
• Interactive guided journey — deferred, not rejected. A step-by-step walkthrough where the user captures and processes a real item during onboarding is a strong pattern but adds significant complexity. The current architecture supports adding this as a future variant (ADR-0036 notes this).

Notes

• Related ADRs: ADR-0034 (flow structure and Tutorial reuse architecture), ADR-0035 (model download screen content), ADR-0036 (sample data strategy).
• "Progressive disclosure" in this ADR refers specifically to time-delayed feature unlocking — not to the UI pattern of expandable sections or "Learn more" links within a single screen, which is encouraged.
• The file layout onboarding/gtd/ and onboarding/vision/ defined in ADR-0034 §2 is the physical home for the reusable concept composables. The tutorials/ NavGraph in Settings imports them from these packages.