ADR-0036: Sample Data Strategy

Context

• Phase 7 onboarding must introduce new users to the GTD-based capture → process → reflect loop.
• Users cannot be assumed to know GTD methodology; for many, LocusFlow will be their first exposure.
• The app starts with empty domain data (no inbox items, processed items, reflections, categories beyond defaults, or contexts beyond defaults).
• The onboarding flow is ~10 screens (ADR-0034) and includes explanatory content about GTD concepts and the reflection loop.
• Pre-populated sample data is a common onboarding technique — seeding the database with example items so users can interact with a non-empty app immediately.
• Categories and contexts already ship with app-supplied defaults (ADR-0012) that are present on fresh install regardless of onboarding.

Constraints:

• The app is pre-release; onboarding content will iterate based on tester feedback.
• Sample data requires maintenance — if the data model changes, sample items must be updated.
• Sample data that is too specific may confuse users or feel inauthentic.
• The app is privacy-focused; any sample data must be obviously synthetic.

Decision

We will not pre-populate domain data during onboarding. The app starts with an empty inbox and no processed items or reflections.

We will rely on in-flow explanatory content — static diagrams, annotated illustrations, and concise text — within the onboarding screens to teach GTD concepts and the app's workflow. No sample inbox items, processed items, or reflections will be seeded into the database.

What the user sees instead of sample data

Empty-state screens

When users reach the main app after onboarding, each list screen (Inbox, Next Actions, Someday/Maybe, etc.) displays a contextual empty-state message with a hint on how to add their first item. These empty states are part of the standard screen design, not onboarding- specific.

Rationale

• Simplicity. Pre-populated sample data requires creating realistic-looking items, maintaining them across schema changes, and providing a "clear sample data" mechanism. For a pre-release app with an evolving data model, this overhead is not justified.
• Authenticity. Users' first experience should be with their own data. Sample items risk creating confusion ("Is this my data? Can I delete it?") and training users to interact with inauthentic content.
• GTD philosophy alignment. GTD emphasizes capturing what is on your mind. Starting empty and prompting users to capture their first thought is more aligned with the methodology than handing them someone else's tasks.
• Sufficient alternative. The onboarding screens provide enough visual context (diagrams, annotated flows) to explain the capture → process → reflect loop without needing live data in the database.
• Default categories and contexts (ADR-0012) already provide a non-empty starting point for the processing flow — users don't face blank dropdowns on their first processing attempt.
• Maintenance cost. Sample data is a testing burden — every schema migration, DAO change, or model update would require sample data validation. Explanatory content is decoupled from the data layer.

Consequences

• Positive:
  • Zero sample-data maintenance overhead.
  • Clean first impression — users start with their own data from the first item.
  • No "clear sample data" UI or logic needed.
  • Onboarding content and domain data are fully decoupled.
• Negative:
  • Users who learn by doing may find the empty app less engaging immediately after onboarding. Mitigated by strong empty-state messaging that prompts first capture.
  • Explanatory diagrams must be clear enough to substitute for hands-on interaction with sample data. Quality of illustrations is critical.
• Follow-up:
  • Empty-state designs for each list screen should guide users toward their first action.
  • A future iteration may introduce a guided journey onboarding variant that walks users through capturing and processing a real item step-by-step. This does not require pre-populated data — it uses live user input instead.
  • If user testing reveals that empty-start is a significant barrier, this ADR can be revisited to introduce optional sample data or a guided capture walkthrough.

Alternatives Considered

• Pre-populated sample inbox items — rejected for this phase. Adds maintenance cost, creates data-authenticity confusion, and is misaligned with GTD's "capture your own stuff" principle. May be reconsidered if testing reveals onboarding comprehension issues.
• Guided first capture (wizard) — deferred, not rejected. A wizard that walks the user through capturing → processing their first real item is a strong onboarding pattern but adds significant implementation complexity. The current architecture (ADR-0034) supports adding this as a future onboarding screen without structural changes.
• Video tutorial — rejected for now. Adds APK size, accessibility overhead (captions), and maintenance cost. Static diagrams are simpler to iterate on during pre-release.

Notes

• Related ADRs: ADR-0012 (categories and contexts with defaults), ADR-0034 (onboarding flow structure), ADR-0038 (onboarding content strategy).
• The decision to start empty applies to domain data only. App-supplied default categories and contexts (ADR-0012) are always present on fresh install and are not considered "sample data."