diff --git a/docs/superpowers/specs/2026-03-15-pricing-signup-three-plan-happy-path-verification-design.md b/docs/superpowers/specs/2026-03-15-pricing-signup-three-plan-happy-path-verification-design.md new file mode 100644 index 0000000..49a302f --- /dev/null +++ b/docs/superpowers/specs/2026-03-15-pricing-signup-three-plan-happy-path-verification-design.md @@ -0,0 +1,127 @@ +# Pricing Signup Flows (Solo, Team, Founder) Happy-Path Verification - Design + +Date: 2026-03-15 +Status: Approved in brainstorming session (user confirmations captured in chat) + +## 1) Problem and Outcome + +We need to verify that the pricing signup flow works correctly for three plans: +- `solo` (monthly) +- `team` (monthly) +- `founder` (yearly) + +Expected product behavior: +- All three plans require card details at signup (immediate Stripe Checkout handoff). +- `solo` and `team` create monthly subscriptions. +- `founder` creates a yearly subscription. + +Desired outcome of this verification cycle: +- Confirm all three happy paths work end-to-end in Stripe test mode. +- Produce clear evidence for each path (redirects, success return, final subscription cadence in app and billing data). + +## 2) Current Context (Observed in Codebase) + +Current code currently exposes signup intent as `trial` or `founder` in `apps/main/src/pages/signup.tsx` and `apps/main/src/hooks/auth.ts`, while checkout API supports `solo`, `team`, and `founder` in `apps/api/src/routers/stripe.ts`. + +This verification scope therefore validates the target intended behavior (3-plan immediate checkout) and is expected to surface any mismatches between signup wiring and checkout capabilities. + +## 3) Scope + +### In scope +- Live Stripe test-mode happy-path verification. +- Three independent signup runs: + - `solo` monthly + - `team` monthly + - `founder` yearly +- End-to-end checkpoints from signup submission to post-payment app state. +- Evidence capture per flow. + +### Out of scope +- Declined cards and other payment failures. +- Checkout cancellation path. +- Webhook delay/retry/failure behavior. +- Automation framework creation (Playwright/Cypress) in this cycle. + +## 4) Verification Architecture + +The verification work is organized into small, independent units: + +1. **Environment Readiness Unit** +- Confirms local app/API are running with Stripe test credentials and webhook forwarding. +- Provides a go/no-go decision before starting flows. + +2. **Plan Execution Unit** +- Executes each plan flow independently with a unique test user. +- Uses a standardized runbook so all plans are evaluated with identical checkpoints. + +3. **Outcome Validation Unit** +- Validates post-checkout state in two layers: + - UI layer: selected plan reflected to the user. + - Billing layer: active subscription interval (`month` vs `year`) and expected plan mapping. + +4. **Evidence and Reporting Unit** +- Captures screenshots, URLs reached, and final observed billing values. +- Produces a concise pass/fail matrix across the three plans. + +These units are intentionally decoupled so each one can be re-run without restarting the whole process. + +## 5) Data Flow to Verify (Per Plan) + +For each of `solo`, `team`, `founder`: + +1. Open signup and select plan. +2. Submit valid user form with a unique test email. +3. Confirm immediate redirect to Stripe Checkout. +4. Enter Stripe test card (`4242 4242 4242 4242`) and complete payment. +5. Confirm return to app success URL. +6. Verify plan/cadence outcome: +- `solo` => active paid subscription, monthly interval. +- `team` => active paid subscription, monthly interval. +- `founder` => active paid subscription, yearly interval. + +## 6) Validation Signals and Evidence + +Per plan, collect: +- Signup plan selection confirmation. +- Checkout page reached (URL and screenshot). +- Success return URL reached (URL and screenshot). +- In-app billing state screenshot. +- Billing data point showing active subscription interval (month/year). + +Recommended reporting structure: +- `plan` +- `checkout reached` +- `payment completed` +- `success redirect` +- `in-app plan state` +- `interval expected` +- `interval observed` +- `result` +- `notes` + +## 7) Error Handling During Happy-Path Runs + +Even in happy-path-only scope, verification should stop and report clearly when a blocking issue appears: +- If checkout redirect does not happen after signup, mark the flow as failed and do not force workarounds. +- If payment succeeds but app state does not update, mark as failed and log whether webhook or sync appears delayed. +- If interval does not match expected cadence, mark as failed and capture exact observed value. + +No failure-path debugging is expanded in this phase; we only capture enough detail to hand off targeted fixes. + +## 8) Test Data Strategy + +- Use one fresh user per plan with timestamped email aliases. +- Keep runs isolated so one failed flow does not contaminate others. +- Avoid reusing pre-existing subscriptions for this phase. + +## 9) Acceptance Criteria + +Verification is successful when all conditions are true: +1. `solo` flow reaches checkout at signup, completes payment, and results in monthly active subscription. +2. `team` flow reaches checkout at signup, completes payment, and results in monthly active subscription. +3. `founder` flow reaches checkout at signup, completes payment, and results in yearly active subscription. +4. Evidence is recorded for each flow with enough detail to reproduce or diagnose. + +## 10) Next Step After This Design + +After spec approval, create an implementation/execution plan for running the live verification and, if needed, patching signup wiring so all three plans trigger immediate checkout.