Onboarding: show value before asking for an account

# Apply the “Onboarding: show value before asking for an account” guide in your agent

## Objective
Start with the smallest useful result a newcomer can achieve. Ask for an account when private access or cross-device persistence requires it. Separate a demo result from saved personal work, and explain what survives leaving the page before someone invests time.

## Prerequisites
- Inspect the repository, documentation, and existing conventions.
- Confirm the need matches the guide scope: Choose a guest trial, a first guided task or mandatory sign-in without losing the work.
- Preserve the correct decisions already in place.

## Guide steps
- 1. Define the first useful result — For a meal planner, the result could be a sample weekly menu. Opening five introduction slides is an activity, not proof of value. Write one observable outcome before designing the welcome screen. List its requirements: example data, preferences, access and persistence. Label fictional data and offer a restart. Never fill a new account with a fake history presented as real.
- 2. Choose the account boundary — Use a guest demonstration for disposable public exploration. Require sign-in first to access hosted private data whose authorization depends on identity. Private work kept locally can remain account-free when local protection is sufficient. A guest path must never bypass authorization or expose another workspace. Explain why sign-in becomes necessary: save across devices, invite someone or access private content. Do not collect unrelated profile fields simply to fill the onboarding journey.
- 3. Example: try a menu — Offer “Try a sample menu” and “Open my menus” separately. Let someone replace one meal and inspect its shopping list. Keep the primary action about that result rather than a tour of every feature. At “Keep this menu”, explain storage. If guest migration exists, transfer exactly the edited version after sign-in and show it again. Otherwise disclose the limitation before editing, without silently discarding work.
- 4. Recover after interruption — A skipped introduction remains available from help. Keep the intended destination through sign-in. After session expiry, distinguish the local draft from what the service has accepted. When sign-in fails, preserve permitted draft fields and offer a safe return. Never say work is saved to an account before the service confirms it. Explain shared-device and local-only limits.
- 5. Verify the promise — Exercise guest use, returning use and failed sign-in. Reopen edited content, follow Back and use the keyboard at narrow width. Verify that the promised data survives rather than checking only a success label. This guide frames a product decision, not identity security or conversion proof. Scripted completion establishes functionality; adoption and learning need separate evidence.

## Acceptance criteria — Verify in your product
- Name the first useful result.
- Identify sample data.
- Explain why an account is needed.
- Preserve promised edits.
- Do not claim success after failure.
- Check skip, back and keyboard.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Anchor the guide in the project

## Objective
Turn the applied steps into durable repository conventions.

## Checks
- Link each decision made to the guide step that justifies it.
- Add the checklist to the relevant reviews.
- Record out-of-scope cases for the neighboring guides.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:8ea61c4a8768a5e2374207a67ad0a43ebeb6c54579f28f95e53f6514f919feed

# Diagnose a failed application of the “Onboarding: show value before asking for an account” guide

## Observed symptom
[DESCRIBE THE SYMPTOM HERE]

## Observable checks
- Replay the steps in order and note the first one that diverges:
- 1. Define the first useful result — For a meal planner, the result could be a sample weekly menu. Opening five introduction slides is an activity, not proof of value. Write one observable outcome before designing the welcome screen. List its requirements: example data, preferences, access and persistence. Label fictional data and offer a restart. Never fill a new account with a fake history presented as real.
- 2. Choose the account boundary — Use a guest demonstration for disposable public exploration. Require sign-in first to access hosted private data whose authorization depends on identity. Private work kept locally can remain account-free when local protection is sufficient. A guest path must never bypass authorization or expose another workspace. Explain why sign-in becomes necessary: save across devices, invite someone or access private content. Do not collect unrelated profile fields simply to fill the onboarding journey.
- 3. Example: try a menu — Offer “Try a sample menu” and “Open my menus” separately. Let someone replace one meal and inspect its shopping list. Keep the primary action about that result rather than a tour of every feature. At “Keep this menu”, explain storage. If guest migration exists, transfer exactly the edited version after sign-in and show it again. Otherwise disclose the limitation before editing, without silently discarding work.
- 4. Recover after interruption — A skipped introduction remains available from help. Keep the intended destination through sign-in. After session expiry, distinguish the local draft from what the service has accepted. When sign-in fails, preserve permitted draft fields and offer a safe return. Never say work is saved to an account before the service confirms it. Explain shared-device and local-only limits.
- 5. Verify the promise — Exercise guest use, returning use and failed sign-in. Reopen edited content, follow Back and use the keyboard at narrow width. Verify that the promised data survives rather than checking only a success label. This guide frames a product decision, not identity security or conversion proof. Scripted completion establishes functionality; adoption and learning need separate evidence.

## Possible causes
- A step was skipped or executed out of order.
- The actual need falls outside the guide scope.
- A checklist criterion was never verified.

## Bounded fixes
- Redo only the diverging step and what depends on it.
- Document the gap if the guide scope does not cover the need.

## Final verification — Verify in your product
- Name the first useful result.
- Identify sample data.
- Explain why an account is needed.
- Preserve promised edits.
- Do not claim success after failure.
- Check skip, back and keyboard.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

• Requires · The real project context: repository, documentation, and existing constraints

# Prevent the next drift

## Objective
Turn the first diverging step into an explicit project check.

## Checks
- Add a focused check on the step that diverged.
- Verify the checklist on a second real case.
- Document the scope limit you hit.

## Guardrails
- Show the proposed changes before any external action.
- Do not publish, send, delete, pay for, or change remote state without explicit authorization.
- Preserve unrelated changes and stop if the scope becomes ambiguous.

## Output format
- Outcome or verdict.
- Files or actions involved.
- Checks run and observable evidence.
- Remaining blockers or limitations.

sha256:a68095c7920994361deb5fd7e713eae6b5f19c7e6996118d8d9293fac185d95b