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 <BIZ> 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/<app>-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

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/<app>/src/components/onboarding/, apps/<app>/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/<app>-onboarding-audit-fact-find.md

Frontmatter (required):

---
Type: Fact-Find
Outcome: Planning
Status: <Ready-for-analysis | Needs-input>
Domain: UI
Workstream: Engineering
Created: <YYYY-MM-DD>
Last-updated: <YYYY-MM-DD>
Feature-Slug: <app>-onboarding-audit
Deliverable-Type: <code-change | multi-deliverable>
Execution-Track: <code | mixed>
Primary-Execution-Skill: lp-do-build
Supporting-Skills: lp-design-system
Related-Analysis: docs/plans/<app>-onboarding-audit-analysis.md
Business-OS-Integration: on
Business-Unit: <BIZ>
---

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:
   Copy

   ### 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 <app> (<BIZ>).

**Audit summary:**
- Sections audited: <N> | Passing: <N> | Failing: <N> | Needs improvement: <N> | N/A: <N>

**Must-have risk check:**
- Aha moment: <Pass | FAIL>
- Sign-up before value: <Pass | FAIL | N/A>
- Funnel analytics: <Pass | FAIL>
- Paywall test strategy: <Pass | FAIL | N/A>

**Top 3 risks:**
1. <Risk 1> (Severity: High | Medium | Low)
2. <Risk 2>
3. <Risk 3>

**Recommended fixes:** P0: <N> | P1: <N> | P2: <N>

**Brief:** `docs/plans/<app>-onboarding-audit-fact-find.md`
**Status:** Ready-for-analysis | Needs-input
**Next:** `/lp-do-analysis <app>-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