--- name: lp-onboarding-audit description: Audit an app's onboarding flow against the "Onboarding Done Right" checklist. Customizes the generic checklist for the app's purpose and audience, then audits actual code using lp-do-fact-find's Outcome A process. Produces an analysis-ready brief. operating_mode: EXECUTE --- # Onboarding Audit Audit an app's onboarding experience against the universal "Onboarding Done Right" checklist (sections A–I). Customizes the checklist for the app's business context, audits actual code, and produces a fact-find brief that feeds into `/lp-do-analysis` before planning. ## When to Use - **DO (`/lp-do-fact-find`)**: When a startup loop card targets onboarding improvement - **L2→L3 readiness**: When a business is launching and onboarding is a critical activation lever - **Standalone**: Operator invokes `/lp-onboarding-audit ` at any time to audit an existing onboarding flow - **Post-launch**: Periodic re-audit to check regression or measure improvement ## Operating Mode **READ + CUSTOMIZE + AUDIT + REPORT** **Allowed:** - Read generic checklist from `.claude/skills/_shared/onboarding-done-right-checklist.md` - Read business strategy plans, brand language docs, businesses.json - Read onboarding component code, routes, layouts, analytics, test files - Trace flow logic and data contracts - Run read-only commands (grep, find, file listing) - Create/update fact-find brief at `docs/plans/-onboarding-audit-fact-find.md` - Create/update Business OS card and stage doc via agent API **Not Allowed:** - Code changes or refactors (use `/lp-do-build` after planning) - Running tests (audit is static analysis + code reading) - User research or live user testing (audit is code-only) - Marking items Pass without citing evidence ## Inputs | Source | Path | Required | |--------|------|----------| | Business unit code | `` (e.g., `BRIK`, `HEAD`, `PET`) | Yes | | Strategy plan | `docs/business-os/strategy//plan.user.md` | Yes | | Business registry | `docs/business-os/strategy/businesses.json` | Yes | | Generic checklist | `.claude/skills/_shared/onboarding-done-right-checklist.md` | Yes | | Brand language | `docs/business-os/strategy//-brand-identity-dossier.user.md` | No — enhances customization | | App name | `` argument (e.g., `prime`) | No — if BIZ has multiple apps | | Scope limit | `--scope A,B,E` argument | No — audit specific sections only | ## Workflow ### Step 1: Resolve Business Context **Goal:** Understand the business, app type, audience, and brand before customizing the checklist. 1. Read `businesses.json` to map BIZ → app list and theme 2. Read strategy plan for: business model, target audience, app purpose, maturity stage 3. Read brand language doc (if exists) for: audience definition, personality, device context 4. If user specified an app, audit that one; otherwise audit all apps for that business 5. **Classify app type** as one of: - Free content app / Free guest companion / Paid app / Freemium - Enterprise/B2B / Admin/internal tool / Booking/commerce / Social/community 6. Document the classification — it drives N/A decisions in Step 2 **Outputs for brief:** - Business Unit, App name(s), App type classification - Target audience summary, Device context, Business model ### Step 2: Customize the Checklist **Goal:** Make the generic checklist specific to this app's purpose. 1. Read `.claude/skills/_shared/onboarding-done-right-checklist.md` 2. For each section A–I: - **Check applicability** using the "App Type N/A Guidance" table - If N/A: document WHY (e.g., "Section F (Paywall) → N/A: Prime is a free guest companion app") - If applicable: write 1–2 sentences translating generic items into this app's context 3. Examples of app-specific interpretation: - Section A (Value-first) for Prime: "Guest sees their personalized arrival plan within 2 screens of starting onboarding" - Section B (Friction) for Prime: "Guest profile capture must justify every field — ETA is critical, room preferences are deferrable" - Section G (Analytics) for a pre-L2 app: "Likely missing entirely — flag as a prerequisite gap" **Outputs for brief:** - Customized checklist with N/A reasoning and app-specific interpretation per section ### Step 3: Audit Actual Onboarding Code **Goal:** Scan the codebase using lp-do-fact-find's evidence audit methodology. 1. **Locate onboarding entry points:** - Search for: `onboard*`, `welcome*`, `setup*`, `guided*`, `activation*` in component names and routes - Common paths: `apps//src/components/onboarding/`, `apps//src/app/onboarding/` - Read layout files, flow components, step components 2. **Trace flow logic:** - Number of steps, conditional branching, skip/exit paths - Data collected at each step (fields, schemas) - Where data is persisted (API calls, local storage, state) 3. **Scan analytics instrumentation:** - Search for `track`, `record`, `analytics`, `event`, `log` in onboarding components - Check: per-step events, completion event, drop-off tracking, error logging - Note any analytics SDK setup (Mixpanel, Amplitude, PostHog, etc.) 4. **Check accessibility:** - Grep for `aria-`, `tabIndex`, `role=`, `focus()`, `label`, `sr-only` - Check touch target sizes in styles - Look for focus management between steps 5. **Check error handling:** - Network failure states, retry logic, validation UX - Loading states (skeleton loaders vs spinners vs nothing) - Timeout handling, session expiry during onboarding 6. **Review test coverage:** - Locate test files for onboarding components - Note what's covered vs gaps - Check for integration/E2E tests of the full flow **If no onboarding flow is found:** STOP. Report that the app has no onboarding and recommend building one. Do not fabricate audit results. **Outputs for brief:** - Component inventory (all onboarding-related file paths) - Flow map (steps → data → persistence → analytics) - Test coverage summary ### Step 4: Score Each Section **Goal:** Produce a Pass/Fail/Partial/N/A verdict for each checklist item with evidence. **Scoring rules:** - **Pass:** Implemented and meets practice — cite component path + line number - **Fail:** Missing, broken, or anti-pattern — explain what's wrong - **Partial:** Implemented with gaps — specify what's missing - **N/A:** Not applicable — reasoning from Step 2 **Section-level verdict:** - >80% of applicable items Pass → **Section passes** - >50% of applicable items Fail → **Section fails** (requires immediate attention) - 50–80% Pass → **Section needs improvement** **Must-have risk items** (from the scoring rubric): - Aha moment not reached quickly → automatic risk flag - Sign-up before value when not required → automatic risk flag - No onboarding funnel analytics → automatic risk flag - No paywall test strategy for paid apps → automatic risk flag ### Step 5: Produce Fact-Find Brief **Goal:** Write an analysis-ready brief using `lp-do-fact-find` Outcome A format. **Output path:** ``` docs/plans/-onboarding-audit-fact-find.md ``` **Frontmatter (required):** ```yaml --- Type: Fact-Find Outcome: Planning Status: Domain: UI Workstream: Engineering Created: Last-updated: Feature-Slug: -onboarding-audit Deliverable-Type: Execution-Track: Primary-Execution-Skill: lp-do-build Supporting-Skills: lp-design-system Related-Analysis: docs/plans/-onboarding-audit-analysis.md Business-OS-Integration: on Business-Unit: --- ``` **Brief sections (in order):** 1. **Scope** — Summary, goals, non-goals, constraints 2. **App Context** — Business unit, app type, audience, device, business model 3. **Evidence Audit** — Component inventory, flow map, data contracts, analytics coverage, test landscape 4. **Customized Checklist** — Section-by-section scores with per-item evidence: ``` ### Section A: Value-first flow **App-specific interpretation:** <1-2 sentences> **Verdict:** Pass | Fail | Needs-Improvement | N/A - [x] A.1 Core promise is benefit-led — **Pass** — `GuestProfileStep.tsx:15` shows "Help us prepare your perfect stay" - [ ] A.2 Aha moment designed — **Fail** — No meaningful result shown; flow ends at generic "Welcome" screen ... ``` 5. **Findings Summary** — Sections passing / failing / needing improvement / N/A 6. **Risks** — Table with top risks, likelihood, impact, mitigation 7. **Recommended Fixes** — Prioritized as P0 (critical) / P1 (important) / P2 (polish), each with component path and expected impact 8. **Confidence Inputs** — Implementation, Approach, Impact, Delivery-Readiness, Testability scores (0–100) for `/lp-do-analysis` 9. **Suggested Task Seeds** — Non-binding task ideas for `/lp-do-analysis` and later `/lp-do-plan` 10. **Analysis Readiness** — Status + blocking items if any ### Step 6: Report Completion **Completion message format:** ``` Onboarding audit complete for (). **Audit summary:** - Sections audited: | Passing: | Failing: | Needs improvement: | N/A: **Must-have risk check:** - Aha moment: - Sign-up before value: - Funnel analytics: - Paywall test strategy: **Top 3 risks:** 1. (Severity: High | Medium | Low) 2. 3. **Recommended fixes:** P0: | P1: | P2: **Brief:** `docs/plans/-onboarding-audit-fact-find.md` **Status:** Ready-for-analysis | Needs-input **Next:** `/lp-do-analysis -onboarding-audit` ``` ## Quality Checks - [ ] Business context resolved (strategy plan read, app type classified) - [ ] Brand language read (if exists) for audience and voice context - [ ] Checklist customized (N/A marked with reasoning, app-specific interpretation per section) - [ ] All onboarding components found and read (not guessed) - [ ] Every Pass/Fail cites component path + line number (no verdicts without evidence) - [ ] Every N/A section has documented reasoning - [ ] Must-have risk items checked (A: Aha, B: sign-up gate, G: analytics, F: paywall) - [ ] At least one risk identified (no "everything is perfect" audits) - [ ] Fact-find brief has all required lp-do-fact-find Outcome A sections - [ ] Confidence inputs provided (5 dimensions, 0–100) - [ ] Analysis readiness status set - [ ] Brief saved at correct path with correct frontmatter ## Integration - **Consumed by**: `/lp-do-analysis` (selects the right onboarding improvement approach before tasking) - **Feeds into**: `/lp-do-plan` and then `/lp-do-build` - **References**: `.claude/skills/_shared/onboarding-done-right-checklist.md` (generic checklist) - **Loop position**: DO (`/lp-do-fact-find`) — specialized fact-find for onboarding audits - **Trigger conditions**: - Card targets onboarding improvement - Business at L2→L3 transition (launch readiness) - Operator invokes manually at any time - **Business OS sync**: Creates card + fact-find stage doc when `Business-Unit` is present ## Red Flags (Invalid Run) 1. **No onboarding found:** If the app has no discoverable onboarding flow, STOP and report. Do not fabricate results. 2. **Business context missing:** If strategy plan doesn't exist and context can't be inferred, STOP and ask user to provide it. 3. **Scoring without evidence:** Every Pass must cite a file path. If you can't find evidence, mark as Fail or Partial, never Pass. 4. **N/A without reasoning:** Every N/A must explain why. "Not applicable" alone is not acceptable. 5. **Zero risks identified:** Every audit must surface at least one risk. If everything genuinely passes, flag the must-have items as the minimum verification. ## Example Invocation ``` /lp-onboarding-audit BRIK /lp-onboarding-audit BRIK prime /lp-onboarding-audit BRIK prime --scope A,B,G ```