@superwall/cli 1.7.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CSzNTGHM.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-C3Q8DBU2.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-BumHTi9O.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Bpviiclc.js} +20 -26
  8. package/dist/client-BL0f_yGf.js +176 -0
  9. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/create-BSfvpWoD.js +19 -0
  12. package/dist/{create-pkANt1Gs.js → create-BUcVG4Ab.js} +195 -169
  13. package/dist/{notification-url-DuKF2659.js → create-CfK3PeKA.js} +235 -539
  14. package/dist/doctor-BWqIYcMn.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-CPhdPkW5.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28072 -1134
  18. package/dist/environment-eBXjELoN.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-BltvQiX5.js} +12 -6
  20. package/dist/held-CPve03KJ.js +16 -0
  21. package/dist/held-DgnTFMl3.js +1112 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-BRsqoe01.js} +277 -254
  24. package/dist/log-NVhVe_oe.js +62 -0
  25. package/dist/login-BCEH5q0U.js +53 -0
  26. package/dist/login-BPOONe7n.js +16 -0
  27. package/dist/{login-Do4wFuLv.js → login-BbTIrCFT.js} +118 -55
  28. package/dist/lookup-rr1AkCJA.js +71 -0
  29. package/dist/migrate-C9X2Vz81.js +274 -0
  30. package/dist/notification-url-CV86qiKP.js +100 -0
  31. package/dist/{open-studio-DOw-6ydc.js → open-CcpXotHG.js} +34 -43
  32. package/dist/org-BQQDo7wm.js +35 -0
  33. package/dist/output-Ggzq5_-t.js +122 -0
  34. package/dist/paths-CRlU72cq.js +29 -0
  35. package/dist/playbook-DVMXN7fh.js +53 -0
  36. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  37. package/dist/promote-Da8xctzy.js +91 -0
  38. package/dist/push-BV-grvQg.js +22 -0
  39. package/dist/push-D6R9icWN.js +495 -0
  40. package/dist/registry-BYVD-_h6.js +10385 -0
  41. package/dist/{reports-CfJqoava.js → reports-D_qbl7_u.js} +7 -6
  42. package/dist/{resources-Bf9O1JNM.js → resources-DLON3-61.js} +162 -55
  43. package/dist/{run-DsVZ5snL.js → run-Co-BwhOg.js} +16 -22
  44. package/dist/scan-B88OlWOt.js +4 -0
  45. package/dist/{scan-zKsddO72.js → scan-CKuk-_6W.js} +48 -37
  46. package/dist/scope-DV22_Ufm.js +198 -0
  47. package/dist/screenshot-file-tVBfUEIi.js +16 -0
  48. package/dist/{selection-CxZoX4NT.js → selection-C2_KbLuo.js} +100 -51
  49. package/dist/server-C4f6ccUr.js +22 -0
  50. package/dist/{dev-DmB3XqaJ.js → server-D0d2oP-5.js} +86 -94
  51. package/dist/session-B-Uz0cQ7.js +40 -0
  52. package/dist/session-BuvArt1j.js +6 -0
  53. package/dist/session-C4rbE3VS.js +796 -0
  54. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  55. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  56. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  57. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  58. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  59. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  60. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  61. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  62. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  63. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  64. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  65. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  66. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  67. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  68. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  69. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  71. package/dist/skills/index.json +37 -0
  72. package/dist/skills/mobile-design/SKILL.md +447 -0
  73. package/dist/skills/mobile-design/references/responsive.md +162 -0
  74. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  75. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  76. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  77. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  78. package/dist/skills/superwall/SKILL.md +82 -9
  79. package/dist/skills/superwall/references/api.md +153 -37
  80. package/dist/skills/superwall/references/apple-setup.md +316 -0
  81. package/dist/skills/superwall/references/asc.md +74 -38
  82. package/dist/skills/superwall/references/data-analytics.md +55 -21
  83. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  84. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  85. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  86. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  87. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  88. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  89. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  90. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  91. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  96. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  97. package/dist/skills/superwall-editor/SKILL.md +61 -0
  98. package/dist/skills/superwall-editor/references/cli.md +135 -0
  99. package/dist/skills/superwall-editor/references/design.md +51 -0
  100. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  101. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  102. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  103. package/dist/skills/superwall-framework/SKILL.md +85 -31
  104. package/dist/skills/superwall-framework/references/cli.md +58 -27
  105. package/dist/skills/superwall-framework/references/examples.md +4 -3
  106. package/dist/skills/superwall-framework/references/layout.md +64 -9
  107. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  108. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  109. package/dist/skills/wwdc/SKILL.md +22 -0
  110. package/dist/skills/wwdc/references/docs.md +52 -0
  111. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  112. package/dist/skills-CLGJuMnF.js +14 -0
  113. package/dist/{skills-DPzlnfCK.js → skills-CZcpnEnG.js} +100 -122
  114. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  115. package/dist/spinner-C2U6QBJ9.js +294 -0
  116. package/dist/storage-6h9vyiAz.js +31 -0
  117. package/dist/storage-CerJ5KLP.d.ts +16 -0
  118. package/dist/storekit-CK9JmM2D.js +16 -0
  119. package/dist/storekit-CinJra3V.js +47 -0
  120. package/dist/telemetry-DKyDhURo.js +56 -0
  121. package/dist/theme-DUsCh-Vd.js +25 -0
  122. package/dist/timing-BVxPrYq3.js +5 -0
  123. package/dist/{token-C0it-Xh7.js → token-DaxQgQkv.js} +6 -38
  124. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  125. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  126. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  127. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  128. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  129. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  130. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  131. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  132. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  133. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  134. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  135. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  136. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  137. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  138. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  139. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  140. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  141. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  142. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  143. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  144. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  145. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  146. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  147. package/dist/tools-skills/superwall/SKILL.md +263 -0
  148. package/dist/tools-skills/superwall/references/api.md +303 -0
  149. package/dist/tools-skills/superwall/references/asa.md +166 -0
  150. package/dist/tools-skills/superwall/references/asc.md +95 -0
  151. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  152. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  153. package/dist/tools-skills/superwall/references/docs.md +51 -0
  154. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  155. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  156. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  157. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  158. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  159. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  160. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  161. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  162. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  163. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  164. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  165. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  166. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  167. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  168. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  169. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  170. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  171. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  172. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  173. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  174. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  175. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  176. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  177. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  178. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  179. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  180. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  181. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  182. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  183. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  184. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  185. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  186. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  187. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  188. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  189. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  190. package/dist/tools.d.ts +96 -0
  191. package/dist/tools.js +11360 -0
  192. package/dist/ui-D_qf3Gvw.js +53 -0
  193. package/dist/upgrade-DPo0a4Es.js +117 -0
  194. package/dist/upgrade-ffseQDMx.js +7 -0
  195. package/package.json +10 -5
  196. package/dist/api-CZzirVMj.js +0 -151
  197. package/dist/api-output-aJNw7Syy.js +0 -20
  198. package/dist/app-DH6U8yuI.js +0 -190
  199. package/dist/asa-C-sQzPPn.js +0 -1194
  200. package/dist/asc-1ZBJ6DwS.js +0 -778
  201. package/dist/auth-YRhlV3DE.js +0 -140
  202. package/dist/billing-CCYHdApx.js +0 -80
  203. package/dist/bundle-id-CKxl_026.js +0 -121
  204. package/dist/command-CMIz81Da.js +0 -301
  205. package/dist/dev-DZy6pOnB.js +0 -22
  206. package/dist/doctor-H-hf-Yww.js +0 -88
  207. package/dist/feedback-CKf-rpBW.js +0 -152
  208. package/dist/hosted-CXe9TrWx.js +0 -32
  209. package/dist/migrate-C9ERDR6y.js +0 -284
  210. package/dist/org-sj7uyvp-.js +0 -40
  211. package/dist/output-C4o2gJ1K.js +0 -146
  212. package/dist/params-l3CrvRtR.js +0 -51
  213. package/dist/pipeline-BqzqZhX1.js +0 -977
  214. package/dist/print-skill-ZojRSybs.js +0 -74
  215. package/dist/promote-BG8X4Nv_.js +0 -88
  216. package/dist/publish-sxLh-G4G.js +0 -35
  217. package/dist/push-bQ6Vxtg8.js +0 -35
  218. package/dist/query-_FbybaH-.js +0 -53
  219. package/dist/resource-CGIwSd29.js +0 -323
  220. package/dist/revenue-provider-ebsRINY8.js +0 -100
  221. package/dist/scope-BvzD-kO4.js +0 -223
  222. package/dist/skills-D_R-lEsK.js +0 -64
  223. package/dist/spinner-TWa0hia6.js +0 -18
  224. package/dist/storekit-Cj9Cpjcz.js +0 -29
  225. package/dist/telemetry-DeA1mvnT.js +0 -169
  226. package/dist/ui-Dy0b-9L8.js +0 -27738
  227. package/dist/update-B2fWIc4q.js +0 -59
  228. package/dist/upgrade-BmzkTKrh.js +0 -72
  229. /package/dist/{devtools-8EgLo86w.js → devtools-pBl_vt03.js} +0 -0
@@ -0,0 +1,231 @@
1
+ ---
2
+ name: onboarding-questions
3
+ description: Write the brains of an app's onboarding or web2app funnel — every question, its answers, the order, the branching, the statements and explainer screens between them, image descriptions and the meaning of each transition — so the flow primes the user to finish and to buy, and collects the answers that predict revenue (from ARPU data across 411 apps). Starts from an App Store URL (and the website, if there is one), researches the app, and hands over a spec that ships fastest as a Superwall surface (the superwall framework: one page per screen, answers sent as user attributes). Design, UI and code agnostic; no paywall, pricing or checkout. Use when the user asks "what should we ask in onboarding", "write our onboarding questions", "design a quiz/survey funnel", "which questions predict who pays", "make our onboarding convert", or wants inspiration for onboarding screens.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Onboarding Questions
8
+
9
+ You're the data-driven cognitive psychologist behind an onboarding flow. You
10
+ decide what the user is asked, in what order, what they're told between
11
+ questions, and what each screen means, so that by the last screen they have
12
+ talked themselves into the app, and the app knows the answers that predict
13
+ whether they'll pay.
14
+
15
+ You write the **spec**, not the product: questions, answers, order, branching,
16
+ statements, explainer screens, image descriptions and what each transition
17
+ should convey. Anyone can build it in any stack or tool. A web funnel's spec
18
+ ends with the App Store link; an in-app flow's ends where the paywall takes
19
+ over.
20
+
21
+ ## Where it ships: a Superwall surface
22
+
23
+ An onboarding is the screen a team changes most after launch — a question
24
+ reordered, a statement swapped, a step cut once the numbers come in — so the
25
+ spec should ship as something that changes without an app release. That is a
26
+ **Superwall surface** built with the superwall framework: one surface in
27
+ `superwall/funnels/<id>/`, one page per screen in `app/`, the progress bar
28
+ and back button in `layout.tsx`, branching as `router.push` from the answer,
29
+ and every attribute in this spec saved with `useUserAttribute` the moment
30
+ it is answered, which is what makes the signal questions do
31
+ anything. The same attributes let a user who quits halfway resume at the
32
+ first unanswered question next time; the build follows `onboarding-state.md`
33
+ in the `superwall-framework` skill (save on tap, never store the step). It
34
+ previews on every device in `superwall dev`, pushes as a
35
+ version, and a campaign switches it live.
36
+
37
+ So when the spec is approved, the next step is to build it there: the
38
+ `superwall-framework` skill carries the how (install it if missing: `npx
39
+ skills add https://github.com/superwall/skills/tree/next --skill
40
+ superwall-framework --global --yes --agent claude-code universal
41
+ --full-depth`), its `onboarding-quiz` and `web-funnel` examples are the two
42
+ shapes this spec takes (in-app before the paywall; on the web before
43
+ install), and `animate-onboarding` turns the transition descriptions below
44
+ into motion. Offer that build in one line when you hand over the spec; the
45
+ user decides. The spec itself stays stack-agnostic so it is usable anywhere.
46
+
47
+ **Not yours:** the paywall, pricing, trials, checkout, visual design, code.
48
+ If asked, say so and point to the right place: the `superwall` skill covers
49
+ paywalls, products and campaigns, and `animate-onboarding` builds the
50
+ motion.
51
+
52
+ The worked example is Reflective's discovery funnel, live at
53
+ https://getreflective.app/flow/reflective-discovery, written out in the output
54
+ format in `references/example-reflective.md`. Read it before writing your
55
+ first spec.
56
+
57
+ ## Files
58
+
59
+ - `references/arpu-questions.md` — the data: which questions split ARPU, by
60
+ how much, overall and per category (411 apps). Every "why ask this" traces
61
+ back here.
62
+ - `references/craft.md` — the psychology, how to write a question, screen
63
+ types, pacing, branching, statements, images and motion, and how to adapt
64
+ each data question to an app's world.
65
+ - `references/example-reflective.md` — a complete spec, as delivered.
66
+
67
+ ## Workflow
68
+
69
+ ### 1. Get the inputs
70
+
71
+ Ask for, in one message:
72
+
73
+ 1. **The App Store URL.** Required. If they give a name instead, find it
74
+ (iTunes Search API, below) and confirm.
75
+ 2. **The website**, if they have one. Optional; the App Store record's
76
+ `sellerUrl` often has it.
77
+ 3. Only if it isn't obvious from the listing: **where the flow runs** (in the
78
+ app before the paywall, or a web funnel before install). It changes two
79
+ things: a web funnel can't ask for permissions, and its answers have to be
80
+ carried through the install to reach the app.
81
+
82
+ Don't ask anything else up front. Research answers the rest.
83
+
84
+ ### 2. Research the app
85
+
86
+ ```bash
87
+ # The record: name, category, description, website, rating, screenshots.
88
+ curl -s "https://itunes.apple.com/lookup?id=<ID>&country=us" | jq '.results[0] | {trackName, sellerName, sellerUrl, primaryGenreName, genres, averageUserRating, userRatingCount, price, description, screenshotUrls}'
89
+
90
+ # What users say, in their words (most recent reviews; pages 1–10).
91
+ curl -s "https://itunes.apple.com/us/rss/customerreviews/page=1/id=<ID>/sortby=mostrecent/json" | jq -r '.feed.entry[]? | "\(.["im:rating"].label)★ \(.title.label): \(.content.label)"'
92
+ ```
93
+
94
+ Then open the App Store page itself (in-app purchases, "What's New"), the
95
+ screenshots (they often show the current onboarding and the promise), and the
96
+ website. The iTunes API is rate-limited (~20 calls/min): cache what you fetch.
97
+
98
+ Write down, before any question:
99
+
100
+ - **What it is and who it's for**, in one sentence each.
101
+ - **The category**, mapped to one of the data's categories (see
102
+ `arpu-questions.md` "By category") by what the app does, not its App Store
103
+ genre (Reflective is filed under Health & Fitness; it's wellness). This
104
+ picks the category questions.
105
+ - **The core promise**: the outcome, not the features.
106
+ - **The pain, in the users' own words**: 3–6 phrases lifted from reviews and
107
+ the listing. These become answer options and statements.
108
+ - **The moment of value**: what they get in the first session.
109
+ - **What they already spend** on the problem (money, time, other apps), if
110
+ anything. An existing spend is the strongest priming material there is.
111
+
112
+ ### 3. Write the arc
113
+
114
+ A flow is a story the user tells themselves. Before any screen, write the arc
115
+ as 4–6 acts, one line each. The default shape:
116
+
117
+ 1. **Identity and investment** — why they're here, what they already put in.
118
+ 2. **Confrontation** — honest questions whose answers reveal the problem.
119
+ 3. **Agitation** — what the problem costs them, in specific moments.
120
+ 4. **Insight** — what they couldn't see on their own; the app's reason to exist.
121
+ 5. **About you** — the short demographic block.
122
+ 6. **Resolution** — one last honest question, then the promise and the App Store.
123
+
124
+ Adapt the acts to the app; keep the direction: from who they are, through the
125
+ problem, to the promise.
126
+
127
+ ### 4. Choose the questions
128
+
129
+ Every screen must earn its place as at least one of:
130
+
131
+ - **Signal**: its answer predicts revenue (the data).
132
+ - **Priming**: its honest answer moves them toward "I need this".
133
+ - **Pacing**: it changes the rhythm so the flow doesn't feel like a form.
134
+
135
+ Build the question list in this order of priority:
136
+
137
+ 1. **The data questions for this category** from `arpu-questions.md`, adapted
138
+ to the app's world (`craft.md` "Adapting the data questions"). Always age,
139
+ source, and a goal asked as a multi-select with the pick count stored. Add
140
+ the category's strong ones (problem size in health, work in productivity
141
+ and design, target date in education and language, who it's for in family,
142
+ gender only where it works: dating, wellness, fitness, entertainment).
143
+ 2. **The priming questions** that walk the arc, built from the pain phrases.
144
+ 3. Cut anything that is neither, and anything that repeats another question.
145
+
146
+ ### 5. Order, branch and pace
147
+
148
+ - The first question comes on the first tap and is easy and about them.
149
+ - A non-question beat (statement, explainer, read-back) every 2–4 questions.
150
+ - Demographics go late, as one block ("A few quick ones, so it fits you"),
151
+ once they're committed; source last in the block. Sensitive ones are
152
+ optional, with an honest opt-out.
153
+ - End on the strongest emotional beat and the promise, never on a
154
+ demographic.
155
+ - Branch only to skip what doesn't apply or to read their answers back; keep
156
+ every branch short so progress stays honest.
157
+ - 15–25 screens is normal for a funnel that sells (Reflective is 24–26).
158
+ - The demographic block counts as questions: four in a row needs a beat
159
+ before the fifth (Reflective reads a number back between work and source).
160
+ Effort in onboarding predicts paying (`arpu-questions.md`), but every screen
161
+ still has to earn its place.
162
+
163
+ Details, and the reasoning, in `craft.md`.
164
+
165
+ ### 6. Write the copy
166
+
167
+ Questions, answers, statements and explainers, following `craft.md`: one idea
168
+ per question, 3–6 answers in the user's voice, an honest way out where one is
169
+ needed, stable machine values for every answer. Every factual claim in a
170
+ statement is true, and listed at the end for the team to verify.
171
+
172
+ ### 7. Describe the images and the motion
173
+
174
+ For every image screen: one or two sentences of what it shows and its mood,
175
+ consistent with the app's existing style (from the screenshots). For every
176
+ transition that carries meaning: what it should convey (the answer becomes
177
+ progress; the price becomes the picture of the investment; the colour of
178
+ their answer fills the next screen). Describe, don't build; `animate-onboarding`
179
+ turns these into motion.
180
+
181
+ ### 8. Deliver the spec
182
+
183
+ One document, in this order (the example shows every section filled in):
184
+
185
+ 1. **The app, read** — the research summary from step 2.
186
+ 2. **The arc** — the acts, one line each.
187
+ 3. **Screens** — numbered, in order. For each: id, type, copy (title,
188
+ subtitle, answers with values), attribute key, purpose (signal / priming /
189
+ pacing, and for signal, the data row it comes from), branching, image
190
+ description, and the transition out.
191
+ 4. **Branching** — every rule, as "after X, if key = value, go to Y", with the
192
+ gating answer checked first so an answer left over from going back can't
193
+ misroute.
194
+ 5. **Attributes** — a table: key, values, source screen, why (data rank and
195
+ spread in this category). These are what the flow sends as user
196
+ attributes the moment each is answered (a web funnel carries them
197
+ through the install). Without this, none of the signal questions do
198
+ anything: they are what campaign audiences and the paywall's
199
+ personalization read.
200
+ 6. **Claims to verify** — every factual statement in the flow.
201
+ 7. **The last screen** — the promise and the App Store link (a web funnel),
202
+ or the promise and the hand-off to the paywall (in-app).
203
+ 8. **What the answers are for, and what they're not** — they predict revenue
204
+ and let the team build audiences; they are not by themselves a reason to
205
+ change the paywall (see the data's Limits).
206
+
207
+ ## Hard rules
208
+
209
+ - **Name the surface once.** The spec is a document for the team, not a
210
+ pitch: it mentions Superwall exactly once, as the one-line build offer at
211
+ the end ("ships fastest as a Superwall surface; say the word"). No hook
212
+ names, no `useUserAttribute` calls, no framework paths in the body; a
213
+ spec that sells the stack three times reads as sales copy and gets
214
+ marked down for it.
215
+
216
+ - **Everything true.** No invented statistics, no fake "analysing your
217
+ answers" delay that computes nothing, no fake scarcity. A statement is a
218
+ known fact (list it for verification) or a common experience framed as one
219
+ ("You're not alone…").
220
+ - **Never tell them they have a problem.** Ask a question whose honest answer
221
+ shows it. They believe what they conclude.
222
+ - **No shaming.** After a vulnerable answer, normalise ("You're not alone"),
223
+ then move on.
224
+ - **Sensitive questions are optional** and respectful: gender asked as "How do
225
+ you describe your gender?" with "I describe it another way" and "Prefer not
226
+ to say"; age includes "Under 18" where minors can use the app.
227
+ - **Stable values.** Every answer has a kebab-case value that never changes
228
+ after launch; audiences are built on them.
229
+ - **No paywall, pricing or checkout.** A web funnel ends at the App Store
230
+ link; an in-app flow ends where the paywall begins. What the paywall says
231
+ is another skill's job.
@@ -0,0 +1,139 @@
1
+ # Onboarding questions that split ARPU
2
+
3
+ This list ranks questions, not answers. A question is good when its answers separate users who pay
4
+ from users who do not, whichever way the answers point. The direction can differ by app. Advanced
5
+ users pay more in photo tools and less in health apps, and the question works in both.
6
+
7
+ The data is 411 apps. All numbers come from `out/concepts.csv` and `out/concept_by_vertical.csv`
8
+ (in the research repo; not shipped with this skill).
9
+
10
+ - **Found / asked.** Apps where the answers split ARPU, over apps that collect the answer and had
11
+ enough data to test it. A skeptic refuted some findings. Those do not count.
12
+ - **Strong.** Apps where the finding has medium or high confidence and the skeptic did not weaken it.
13
+ - **Spread.** The ARPU of the best answer divided by the ARPU of the worst, inside one paywall
14
+ variant and one currency. The table gives the median across apps.
15
+ - **Rule.** Share of findings where the customer has an audience rule on the key today.
16
+
17
+ ## The ranked list
18
+
19
+ | # | Ask | Found / asked | Strong | Spread, max | Rule | Verticals |
20
+ |---|---|---|---|---|---|---|
21
+ | 1 | How old are you? | 81 / 83 | 67 | 2.89, 13.1 | 36% | 21 |
22
+ | 2 | How did you hear about us? | 42 / 42 | 26 | 2.03, 5.48 | 2% | 17 |
23
+ | 3 | What do you do for work? Is this for work, school, or personal use? | 24 / 29 | 18 | 2.64, 7.9 | 22% | 9 |
24
+ | 4 | How big is the problem today? (hours lost, symptoms, weight to lose, amount owed) | 52 / 55 | 36 | 1.54, 7.38 | 3% | 19 |
25
+ | 5 | What is your main goal? | 79 / 89 | 47 | 1.64, 3.28 | 8% | 21 |
26
+ | 6 | By when do you need it? (exam, trip, event, target date) | 11 / 13 | 7 | 1.92, 3.14 | 7% | 6 |
27
+ | 7 | Which of these apply to you? Multi-select, and store the count of picks | 44 / 57 | 29 | 1.78, 6.57 | 0% | 18 |
28
+ | 8 | Which topic or content do you want? (language, diet, sport, genre) | 69 / 80 | 34 | 1.60, 4.5 | 8% | 18 |
29
+ | 9 | Who is this for? (me, partner, kids, family, team) | 12 / 16 | 8 | 1.85, 3.89 | 8% | 8 |
30
+ | 10 | How often will you do this? | 24 / 32 | 19 | 1.62, 2.6 | 3% | 12 |
31
+ | 11 | Height, weight, and target weight | 10 / 12 | 5 | 1.69, 2.35 | 0% | 3 |
32
+ | 12 | Relationship, kids, pregnancy week, child age | 11 / 13 | 4 | 1.57, 5.5 | 15% | 8 |
33
+ | 13 | What have you tried before? | 17 / 24 | 12 | 1.54, 2.25 | 0% | 8 |
34
+ | 14 | How experienced are you? | 31 / 45 | 19 | 1.42, 3.63 | 8% | 14 |
35
+ | 15 | Where do you shop? What do you spend on this today? | 9 / 16 | 6 | 1.72, 2.75 | 10% | 5 |
36
+ | 16 | Gender | 36 / 62 | 19 | 1.69, 3.9 | 11% | 14 |
37
+
38
+ Age, source, and problem size work in almost every app that asks them. Age and work have the largest
39
+ spread. Almost no customer has a rule on source, problem size, or pick count, so those are open.
40
+
41
+ Experience level works in two of three apps that ask it. It is strongest in language apps (6 of 6)
42
+ and lifestyle apps (5 of 5). It is a null in four sports apps.
43
+
44
+ Gender fails in 26 of 62 apps. Ask it in dating (6 of 7, spread 2.47) and in wellness (6 of 7). It
45
+ is a null in 10 of 12 health apps.
46
+
47
+ ## Three signals that cost no screen
48
+
49
+ Store these beside any answer.
50
+
51
+ - **Count of picks in a multi-select.** 44 of 57 apps. One pick pays least. The count matters more
52
+ than which option the user picks.
53
+ - **Effort in onboarding.** 69 of 111 apps, spread 1.61. Long free-text answers, no skipped steps,
54
+ and more seconds in onboarding all mark users who pay more.
55
+ - **Permission answers.** 45 of 63 apps, spread 1.64. A user who refuses push or tracking pays 0.38
56
+ to 0.74.
57
+
58
+ ## By category
59
+
60
+ Each line gives the question, then found / asked, the strong count, and the median spread. Questions
61
+ with no strong app are left out. The app count is the number of apps in the category.
62
+
63
+ **Health and nutrition (41).** Problem size 11/11, 10 strong, 1.42. Age 12/13, 9 strong, 1.74. Source
64
+ 7/7, 7 strong, 2.25. Goal 11/13, 6 strong, 1.59. Pick count 10/11, 6 strong, 1.66. Who it is for 4/6,
65
+ 4 strong, 1.47. Diet or condition 10/11, 3 strong, 1.60. Body metrics 4/4, 3 strong, 1.82.
66
+
67
+ **Productivity and screen time (23).** Age 8/8, 8 strong, 7.03. This is the largest age spread of any
68
+ category. Goal 7/8, 5 strong, 1.98. Source 4/4, 4 strong, 2.98. Work 5/5, 3 strong, 3.42. Problem size
69
+ 7/7, 3 strong, 2.12. What they tried before 4/4, 3 strong, 1.62.
70
+
71
+ **Lifestyle (30).** Age 8/8, 8 strong, 2.33. Goal 9/12, 5 strong. Pick count 7/8, 5 strong, 2.05.
72
+ Frequency 6/6, 5 strong. Problem size 6/6, 4 strong, 1.87. Source 5/5, 4 strong. Experience 5/5, 4
73
+ strong, 1.38.
74
+
75
+ **Fitness (22).** Age 12/12, 8 strong, 3.17. Gender 4/7, 3 strong, 1.37. Goal 5/6, 2 strong, 1.99.
76
+ Experience 3/5, 2 strong, 1.97. Source 4/4, 1 strong. Body metrics 4/4, 1 strong.
77
+
78
+ **Dating and social (21).** Age 8/8, 8 strong, 3.43. Gender 6/7, 5 strong, 2.47. Work 1/1, 2.86.
79
+
80
+ **Wellness and mental health (21).** Age 8/8, 7 strong, 3.53. Goal 8/9, 5 strong. Problem size 6/8, 5
81
+ strong, 1.73. Work 4/4, 4 strong, 3.67. Budget 3/3, 3 strong, 2.52. Source 5/5, 3 strong, 2.37. Pick
82
+ count 4/5, 3 strong. Gender 6/7, 3 strong.
83
+
84
+ **Language learning (10).** Target language 6/6, 6 strong, 1.70. Level 6/6, 4 strong, 1.56. Goal 4/4,
85
+ 3 strong, 1.86. Target date 3/3, 2 strong, 1.99.
86
+
87
+ **Education, other (17).** Goal 4/4, 3 strong. Study time 3/4, 3 strong, 2.42. Exam date 3/3, 3
88
+ strong, 1.71. Work or school level 2/2, 2 strong, 3.59. What they tried before 2/3, 2 strong.
89
+
90
+ **Design and creative (20).** Work 3/4, 2 strong, 4.18. Goal 4/4, 2 strong, 2.29. Age 2/2, 1 strong.
91
+
92
+ **Photo and video (35).** Goal or tool they came for 5/5, 2 strong, 1.62. Work 4/5, 2 strong, 2.07.
93
+ Few apps in this category ask anything.
94
+
95
+ **Sports (17).** Goal 4/4, 3 strong. Which sport 8/9, 3 strong, 1.42. Age 2/2, 2 strong, 3.38. Draft
96
+ or season date 1/1, 2.57.
97
+
98
+ **Music (9).** Pick count 2/2, 2 strong, 2.23. Genre 2/2, 2 strong. Goal 2/2, 2 strong. Age 1/1, 6.17.
99
+
100
+ **Faith (12).** Age 2/2, 2 strong, 6.54. Problem size 2/2, 2 strong, 1.96. Goal 2/3, 2 strong.
101
+
102
+ **Games (9).** Age 2/2, 2 strong, 6.0. Who they play with 1/1, 3.42, not yet strong.
103
+
104
+ **Kids and family (6).** Who it is for, or the user's role in the family, 2/2, 2 strong, 3.46.
105
+
106
+ **Women's health (5).** Age 1/1, 10.26. Life stage 1/1, 2.81. Journey type 1/1, 2.77.
107
+
108
+ **Entertainment (14).** Genre 5/5, 3 strong. Age 3/3, 2 strong. Pick count 3/3, 2 strong. Gender 2/3,
109
+ 2 strong, 2.04.
110
+
111
+ **Finance (11).** Problem size (amount owed or missed) 2/2, 2 strong, 1.83.
112
+
113
+ **Business and pro tools (11).** Trade or content type 2/2, 2 strong. Goal 1/1, 2.85. Source 1/1,
114
+ 2.45. Work 1/1, 2.19.
115
+
116
+ **Utilities, scanners, AI assistants, travel, news (77 apps).** Almost none ask an onboarding
117
+ question. Age worked in the 5 of 6 apps that have it, with spreads of 2.0 to 3.0. The first gain here
118
+ is to ask anything at all. Start with age, source, and goal.
119
+
120
+ ## What to ask first
121
+
122
+ An app with no onboarding questions should add these four, in this order:
123
+
124
+ 1. Age.
125
+ 2. How did you hear about us?
126
+ 3. Main goal, as a multi-select, with the pick count stored.
127
+ 4. The category question from the list above: problem size in health, work in design and
128
+ productivity, target date in education and travel, who it is for in family apps.
129
+
130
+ 102 of 411 apps have no finding from a user attribute at all. The health report says that 21 of its
131
+ 40 apps send no onboarding answer to Superwall, and most of them ask the questions in the app. For
132
+ those apps the work is one `setUserAttributes` call.
133
+
134
+ ## Limits
135
+
136
+ - An answer that predicts ARPU is not yet a reason to change the paywall. `REPORT.md` section 4 lists
137
+ the tests where the best paywall flips by answer. Only 25 of 721 such tests are confirmed.
138
+ - Apps that ask a question differ from apps that do not. The find rates hold for apps that ask.
139
+ - A skeptic reviewed 57% of the findings. `out/findings.csv` has the verdict for each.
@@ -0,0 +1,142 @@
1
+ # Craft: writing a flow that primes, finishes, and predicts
2
+
3
+ ## The psychology, and what each principle asks of a screen
4
+
5
+ | Principle | What it means here | How a screen uses it |
6
+ |---|---|---|
7
+ | **Self-persuasion** | People believe conclusions they reach more than claims they're told. | Ask a question whose honest answer shows the problem ("Can you remember the most important thing from your last session?"). Never state it for them. |
8
+ | **Commitment and consistency** | Small yeses make the next yes easier; people act in line with what they've said about themselves. | Open with easy, identity-affirming questions. Build to the bigger admissions. End with one question whose answer *is* the case for the app ("Be honest: how much of what you pay for do you actually keep?"). |
9
+ | **Existing spend as the anchor** | A price is judged against what's already being spent on the problem. | If they already spend (therapy, a gym, tutoring, a coach, other apps), ask how much, then make that investment vivid on the next screen. The app later looks small beside it. The price itself is never mentioned. |
10
+ | **Normalising** | A vulnerable answer followed by judgement ends the flow; followed by "you're not alone" it deepens it. | After the answer that admits the problem, a screen that says it's common (true, and framed as common experience). |
11
+ | **Curiosity** | An open question pulls attention forward. | "Did you know…" statements: one surprising, true, useful fact tied to the answer just given. |
12
+ | **Future pacing** | A goal with a date and a size feels reachable, and worth equipment. | Ask for the target date (adapted to the app's world), then read it back as something concrete: "That's about 26 sessions between now and then." |
13
+ | **Effort creates value** | What people build, they value, and effort in onboarding predicts paying (69 of 111 apps). | Let the answers visibly shape what comes next (read-backs, "your plan"), and take a free-text answer where it's natural. Never pad for effort's sake. |
14
+ | **Goal gradient** | People speed up as a goal gets close. | A visible, honest progress indicator that moves with every answer. Branches stay short so it never jumps backward or stalls. |
15
+ | **Peak–end** | An experience is remembered by its strongest moment and its end. | The last screens are the emotional peak and the promise; demographics come just before, never last. |
16
+
17
+ ## Writing a question
18
+
19
+ - **One idea**, in the second person, as said aloud: "How often do you see your
20
+ therapist?", not "Session frequency".
21
+ - **Short**: a title a thumb can read in one glance (aim for under ~15 words;
22
+ a vivid scenario can run longer: "Something big happens mid-week that you
23
+ want to bring up. What usually happens?").
24
+ - **Ask about behaviour and moments, not opinions**: "What usually happens?"
25
+ beats "How important is remembering?".
26
+ - **3–6 answers.** Mutually exclusive for single-select. Ordered: scales run
27
+ one direction (low → high or most → least) and keep it across the flow.
28
+ - **Answers in the user's voice**: "Honestly… no", "It's usually gone by
29
+ session day", "No rush, it takes what it takes". Lift phrases from reviews.
30
+ - **An honest way out** where someone might not fit: "Something else", "I'm
31
+ not sure", "Prefer not to say". Not on every question: a way out on a
32
+ priming question lets people skip the realisation.
33
+ - **Ranges, not free numbers**, for anything you'll segment on (age, spend,
34
+ hours). Clean boundaries (18–24, 25–34…), no overlaps, no gaps.
35
+ - **Single-select advances on tap** (no Continue button). Multi-select has a
36
+ Continue button that's off until one is picked, and says "Select all that
37
+ apply."
38
+ - **Every answer has a stable value** (kebab-case, `"between-jobs"`), and every
39
+ question an attribute key (`work`). Values never change after launch.
40
+ - **Data questions stay neutral; priming questions may be vivid.** A question
41
+ can be both: "How much does a session cost you?" is a budget signal and the
42
+ set-up for "the biggest investment you make in yourself".
43
+
44
+ ## Adapting the data questions to the app's world
45
+
46
+ The data names concepts; the flow asks them in the app's language. Find the
47
+ version a user of *this* app would answer without thinking.
48
+
49
+ | Data question | Adapt it as | Examples |
50
+ |---|---|---|
51
+ | Age | Ranges; include "Under 18" if minors can use the app. Introduce the demographic block once: "A few quick ones, so [app] fits you." | 18–24 / 25–34 / 35–44 / 45–54 / 55+ |
52
+ | Source | Last in the demographic block. Options are the app's real channels plus "A friend" and the category's authority. | Therapy: "My therapist". Fitness: "My trainer". Education: "My teacher / school". |
53
+ | Work | "What do you do?" or "Is this for work, school, or you?" | Student / Working / Between jobs / Parent at home / Retired; design tools: Freelancer / In-house / Agency / Student / Hobby |
54
+ | Problem size | The unit the user already measures the problem in. | Hours lost a week, weight to lose, amount owed, nights of bad sleep, how long insights last |
55
+ | Goal (multi-select + count) | "What brought you here?" as reasons they'd recognise; store the count. | Therapy: what brought you to therapy. Fitness: what you want to change. |
56
+ | Target date | The moment the user is working toward, even when the app has no deadline. Make it the *other side* of the goal. | Exam date, trip date, wedding, season start, "When would you like to feel like you're on the other side of it?" |
57
+ | Who it's for | Only if the app serves more than one person. | Me / My partner / My kids / My team |
58
+ | Frequency | How often they do the underlying thing today. | Sessions a week, workouts a week, study days |
59
+ | Tried before | What they do *now* instead; doubles as competitor research. | Nothing / Notes app / A journal / Another app |
60
+ | Experience | Only where it works (language, lifestyle); it's a null in sports. | Beginner / Some / Confident |
61
+ | Spend today | What they already pay to solve it. Priming and signal at once. | Per session, per month, per class |
62
+ | Gender | Only in dating, wellness, fitness, entertainment. Optional, skippable, respectful. | "How do you describe your gender?" Woman / Man / Non-binary / I describe it another way / Prefer not to say |
63
+ | Life stage | Only where the app follows one (women's health, family). | Pregnancy week, child's age, trying to conceive |
64
+
65
+ A read-back turns two answers into one concrete picture. Combine a date with
66
+ a frequency ("That's about 26 sessions between now and then"), a problem size
67
+ with a year ("That's 150 hours a year"), a spend with a month. Show it only
68
+ when both answers exist; otherwise skip the screen.
69
+
70
+ ## Screen types
71
+
72
+ Design agnostic; name them so the builder knows the job.
73
+
74
+ | Type | Job | Notes |
75
+ |---|---|---|
76
+ | **Welcome** | The promise in one line, and one image. | "Your therapy deserves a memory." One button. |
77
+ | **Single-select** | Most questions. | Advances on tap. |
78
+ | **Multi-select** | Goals, reasons, "which apply". | Store the pick count. |
79
+ | **Statement** | A "Did you know…" beat, or a read-back. | One sentence, true; on a full-screen colour it lands as a pause. |
80
+ | **Explainer** | The insight after a run of questions: the app's reason to exist. | Headline, one line of body, one image. |
81
+ | **Input** | A free-text answer (a name, the thing they're working on). | Sparingly; long answers mark payers, a required text field loses people. |
82
+ | **Permission primer** | In-app only: why notifications help, then the system prompt. | Its answer predicts paying (45 of 63 apps). A web funnel can't ask. |
83
+ | **Done** | The promise again, and the App Store link. | The last screen; its button opens the App Store URL. |
84
+
85
+ ## Pacing
86
+
87
+ - First question on the first tap.
88
+ - A non-question beat every 2–4 questions: statement, explainer, read-back.
89
+ - Group the demographic questions into one late block, source last.
90
+ - 15–25 screens; count them and justify each (signal / priming / pacing).
91
+ - The final question is the emotional peak ("Be honest: …"), then the promise.
92
+
93
+ ## Branching
94
+
95
+ - Branch to **skip what doesn't apply** ("It's more about ongoing growth"
96
+ skips the target date) or to **show a read-back only when its inputs exist**.
97
+ - Keep branches to 1–2 screens so progress stays honest.
98
+ - Write every rule as "after X, if key = value, go to Y", **gating answer
99
+ first**: a user who goes back and changes an earlier answer leaves the old
100
+ later answer in state, and the rules must not trust it.
101
+ - Never branch into a dead end or a screen whose copy depends on an answer
102
+ that might be missing; give read-backs a fallback line.
103
+
104
+ ## Statements and explainers
105
+
106
+ - One sentence for a statement, one headline and one line for an explainer.
107
+ - **True.** A known finding (list it under "Claims to verify") or a common
108
+ experience framed as one ("You're not alone — most of what we hear is gone
109
+ within a day" rests on the forgetting curve; it's listed for verification).
110
+ - Tied to the answer just given, in its language.
111
+ - The explainer after a run of questions names the insight, then says what the
112
+ app does about it in one clause ("Reflective connects your sessions across
113
+ weeks and months, so you can see the themes your memory can't.").
114
+
115
+ ## Images
116
+
117
+ - One per explainer and the welcome and done screens; none on questions.
118
+ - Describe subject, composition and mood in one or two sentences, in the
119
+ app's existing style (from its screenshots): "An open journal on a warm,
120
+ textured background, soft pink and olive shapes; calm, quiet."
121
+ - Make the image the *picture of the answer before it* where you can: after
122
+ "How much does a session cost you?", an empty armchair and a cup of tea (the
123
+ investment); after a question about patterns, a small sprout (growth). Then
124
+ the answer can visibly become the image.
125
+
126
+ ## Motion (describe the meaning; `animate-onboarding` builds it)
127
+
128
+ For each transition that carries meaning, one line on what it conveys:
129
+
130
+ - **The answer becomes progress**: the chosen answer travels into the progress
131
+ indicator and grows it. The default for questions.
132
+ - **The answer becomes the picture**: the chosen answer opens into the next
133
+ screen's image (the price becomes the picture of the investment).
134
+ - **The answer becomes the moment**: the chosen answer's colour fills the next
135
+ screen, a statement on it.
136
+ - **The moment becomes progress**: the statement's colour collapses into the
137
+ progress indicator.
138
+ - **Forgetting**: a screen fades to nothing before an image arrives ("gone
139
+ within a day").
140
+ - **A jolt**: a quick cut before "Something big happens…".
141
+
142
+ Name the idea, not the implementation.
@@ -0,0 +1,117 @@
1
+ # Example spec: Reflective discovery funnel
2
+
3
+ A complete spec, in the format the skill delivers. It's live at
4
+ https://getreflective.app/flow/reflective-discovery (a web funnel before
5
+ install).
6
+
7
+ ## 1. The app, read
8
+
9
+ - **What it is:** a therapy companion that turns sessions into private notes,
10
+ summaries and themes over time. Not therapy; supports it.
11
+ - **Who it's for:** people in regular talk therapy who want more out of it.
12
+ - **Category:** Wellness and mental health (the App Store files it under
13
+ Health & Fitness; map by what the app does, not the store genre).
14
+ - **Core promise:** your therapy deserves a memory: keep what you learn, and
15
+ see the patterns over time.
16
+ - **The pain, in users' words:** "what did we even talk about last time?";
17
+ re-explaining things already covered; a breakthrough gone by next week;
18
+ something big mid-week forgotten by session day.
19
+ - **Moment of value:** the first captured session, summarised.
20
+ - **What they already spend:** therapy itself, often $100–$200 a session,
21
+ every week or two. The strongest priming material in the flow.
22
+
23
+ ## 2. The arc
24
+
25
+ 1. **Investment** — why they're in therapy, what they're working toward, how
26
+ often, and what it costs.
27
+ 2. **Confrontation** — can they remember their last session? Have they lost a
28
+ breakthrough?
29
+ 3. **Agitation** — re-explaining, what they do now, the mid-week moment.
30
+ 4. **Pattern blindness** — they can't name their own pattern; the app can.
31
+ 5. **About you** — age, gender, work, a read-back breather, source.
32
+ 6. **Resolution** — "how much do you actually retain?", then the promise.
33
+
34
+ ## 3. Screens
35
+
36
+ Purpose: **S** signal (with the data row), **P** priming, **Pa** pacing.
37
+
38
+ | # | id | Type | Copy | Answers (value) | Key | Purpose | Branch | Image | Transition out |
39
+ |---|---|---|---|---|---|---|---|---|---|
40
+ | 1 | welcome | Welcome | **Your therapy deserves a memory.** Capture sessions, revisit insights, and spot patterns that would otherwise fade by next week. Button: Get Started | — | — | P | — | An open journal with faint handwriting, on a warm textured background with soft pink and olive shapes. Calm, private. | The welcome leans back and floats away like a card; the progress bar draws in. |
41
+ | 2 | what-brought-you | Multi-select | **What brought you to therapy?** Select all that apply. Button: Continue | Anxiety (anxiety), Relationships (relationships), A big life change (life-change), Understanding myself (self-understanding), Something else (other) | reason, reasonCount | S: goal + pick count (#5, #7); P: identity | — | — | Every picked answer travels into the progress bar, a beat apart; the last one grows it. |
42
+ | 3 | something-specific | Single | **Is there something specific you started therapy to work through?** | Yes, one thing in particular (one), A few things (few), It's more about ongoing growth (ongoing) | specific | S: sets up target date (#6); P | ongoing → 5 | — | The answer becomes progress. |
43
+ | 4 | target-date | Single | **When would you like to feel like you're on the other side of it?** | In the next 3 months (3-months), Within 6 months (6-months), Within a year (1-year), No rush, it takes what it takes (no-rush) | targetDate | S: target date (#6), the "other side" of therapy | — | — | The answer becomes progress. |
44
+ | 5 | session-frequency | Single | **How often do you see your therapist?** | Every week (weekly), Every two weeks (biweekly), About once a month (monthly), I'm just getting started (starting) | frequency | S: frequency (#10); with cost, monthly spend | see §4 | — | Into 6: the answer's colour fills the screen. Otherwise it becomes progress. |
45
+ | 6 | sessions-ahead | Statement (read-back) | Eyebrow: Picture it… **That's about {N} sessions between now and then.** Each one is worth remembering. Reflective keeps them all, so you can see how you got there. (Fallback title: Every session between now and then is a step toward it.) | — | — | P: future pacing | — | Full-screen answer colour. | The colour collapses into the progress bar. |
46
+ | 7 | session-cost | Single | **How much does a session cost you?** | Under $50 (lt-50), $50–$100 (50-100), $100–$200 (100-200), $200+ (gt-200), Insurance covers it (insurance) | cost | S: budget, strong in wellness (3/3, 2.52); P: existing spend | — | — | The chosen price opens into the next screen's image. |
47
+ | 8 | investment-explainer | Explainer | **Therapy is one of the biggest investments you make in yourself.** An hour of your time, your energy, and your money — every single week. It deserves to stick. | — | — | P: the investment made vivid | — | An empty armchair beside a small table with a closed book and a steaming cup. Someone's hour, waiting. | The big picture sinks back; the next question rises slowly. |
48
+ | 9 | last-session-recall | Single | **Think about your last session. Can you remember the most important thing you talked about?** | Yes, clearly (clearly), Bits and pieces (bits), Honestly… no (no) | recall | P: self-persuasion; S: problem size (#4) | — | — | The answer's colour fills the screen. |
49
+ | 10 | did-you-know-writing | Statement | Eyebrow: Did you know… **Writing down what you learned right after a session helps it stick.** | — | — | P, Pa | — | Full-screen colour. | The colour collapses into the progress bar. |
50
+ | 11 | lost-breakthrough | Single | **Ever had a real breakthrough in a session — and lost it by the next week?** | More than once (many), Once or twice (few), I'm not sure (unsure), Never (never) | breakthrough | P; S: problem size | — | — | Everything fades to nothing; a beat of emptiness before the image. |
51
+ | 12 | forgetting-explainer | Explainer | **You're not alone — most of what we hear is gone within a day.** The hours after therapy are when insights are freshest. Reflective captures them before life takes over. | — | — | P: normalising after an admission | — | Two cupped hands holding a dandelion seed head, glowing softly. Fragile, precious. | The image lifts away first, then the words. |
52
+ | 13 | re-explaining | Single | **Do you spend the first 10 minutes of sessions re-explaining things you've already covered?** | All the time (always), Sometimes (sometimes), Never (never) | reexplain | P; S: problem size | — | — | The answer's colour fills the screen. |
53
+ | 14 | did-you-know-notes | Statement | Eyebrow: Did you know… **Walking in with notes from last time lets you pick up where you left off, instead of starting over.** | — | — | P, Pa | — | Full-screen colour. | Into the progress bar. |
54
+ | 15 | how-you-remember | Single | **What do you do now to remember your sessions?** | Nothing, really (nothing), Notes on my phone (notes-app), A journal (journal), Voice memos (voice-memos), Another app (other-app) | remembering | S: tried before (#13); competitor research | — | — | A quick cut. |
55
+ | 16 | mid-week-moment | Single | **Something big happens mid-week that you want to bring up. What usually happens?** | I remember it (remember), I hope I remember it (hope), It's usually gone by session day (gone) | midweek | P; S: problem size | — | — | The answer's colour fills the screen. |
56
+ | 17 | did-you-know-between | Statement | Eyebrow: Did you know… **A lot of therapy's work happens between sessions: in what you notice, try, and remember.** | — | — | P, Pa | — | Full-screen colour. | Into the progress bar. |
57
+ | 18 | name-your-pattern | Single | **Could you name the emotional pattern that showed up most for you last month?** | Yes, easily (easily), Maybe, if I thought hard (maybe), No idea (no-idea) | pattern | P: sets up the insight | — | — | The other answers gather into the chosen one as it opens into the image: many weeks, one view. |
58
+ | 19 | patterns-explainer | Explainer | **Patterns are invisible one week at a time.** Reflective connects your sessions across weeks and months, so you can see the themes your memory can't. | — | — | P: the app's reason to exist | — | A small two-leaf sprout on a pale background with soft shapes and a thin winding line. Growth, slowly. | Sinks back; the next question rises. |
59
+ | 20 | age | Single | **How old are you?** A few quick ones, so Reflective fits you. | Under 18 (under-18), 18–24, 25–34, 35–44, 45–54, 55+ (18-24 … 55-plus) | age | S: #1; wellness 8/8, 3.53 | — | — | Into progress. |
60
+ | 21 | gender | Single, skippable | **How do you describe your gender?** Optional. It helps us tailor Reflective to you. | Woman (woman), Man (man), Non-binary (non-binary), I describe it another way (self-described), Prefer not to say (prefer-not-to-say) | gender | S: works in wellness (6/7) | — | — | Into progress. |
61
+ | 22 | work | Single | **What do you do?** | Student (student), Working (working), Between jobs (between-jobs), Parent at home (parent-at-home), Retired (retired) | work | S: #3; wellness 4/4, 3.67 | — | — | Into progress. |
62
+ | 23 | sessions-a-year | Statement (read-back) | Eyebrow: Almost there **That's about {N} sessions a year worth keeping.** Reflective holds every one of them. (Fallback title: Every session is worth keeping.) | — | — | Pa; P: future pacing | — | Full-screen answer colour. | The colour collapses into the progress bar. |
63
+ | 24 | source | Single | **How did you hear about Reflective?** | A friend (friend), My therapist (therapist), TikTok (tiktok), Instagram (instagram), The App Store (app-store), Somewhere else (other) | source | S: #2; 2% of apps have a rule on it | — | — | The page settles; the honest question arrives calmly. |
64
+ | 25 | retention | Single | **Be honest: how much of what you pay for therapy do you actually retain?** | Most of it (most), About half (half), Less than half (less) | retention | P: the peak, the case for the app in their words | — | — | The bar fills its last stretch, holds, then gives way. |
65
+ | 26 | done | Done | Eyebrow: You're all set **Make every session count.** Download Reflective on the App Store and start your first session whenever you're ready. Button: Start Reflecting → App Store | — | — | — | — | The open journal again, now with a single green leaf resting on its pages. | — |
66
+
67
+ ## 4. Branching
68
+
69
+ - After **3 something-specific**: if `specific = ongoing` → 5; else → 4.
70
+ - After **5 session-frequency**, in order:
71
+ 1. if `specific = ongoing` → 7 (checked first: a date left over from before
72
+ they went back and chose ongoing must not count);
73
+ 2. if `targetDate = no-rush` → 7;
74
+ 3. if `frequency = starting` → 7;
75
+ 4. else → 6.
76
+ - **6 sessions-ahead:** N = weeks × sessions per week, rounded; weeks: 3-months
77
+ 13, 6-months 26, 1-year 52; per week: weekly 1, biweekly 0.5, monthly 12/52.
78
+ If either answer is missing, the fallback title.
79
+ - **23 sessions-a-year:** N = sessions per year from `frequency`: weekly 52,
80
+ biweekly 26, monthly 12; `starting` or missing → the fallback title. A beat
81
+ inside the demographic block, so no run of questions passes four (20–22,
82
+ then 24–25).
83
+
84
+ ## 5. Attributes
85
+
86
+ Sent to Superwall as user attributes (carried through the install, since
87
+ this is a web funnel).
88
+
89
+ | Key | Values | Screen | Why |
90
+ |---|---|---|---|
91
+ | age | under-18, 18-24, 25-34, 35-44, 45-54, 55-plus | 20 | #1 overall; wellness 8/8, 7 strong, 3.53 |
92
+ | work | student, working, between-jobs, parent-at-home, retired | 22 | #3; wellness 4/4, 4 strong, 3.67 (the largest in the category) |
93
+ | source | friend, therapist, tiktok, instagram, app-store, other | 24 | #2; wellness 5/5, 2.37; almost no one has a rule on it |
94
+ | reason, reasonCount | multi; count 1–5 | 2 | goal (#5) and pick count (#7): one pick pays least |
95
+ | cost | lt-50, 50-100, 100-200, gt-200, insurance | 7 | budget, wellness 3/3, 2.52 |
96
+ | frequency | weekly, biweekly, monthly, starting | 5 | #10; with cost, monthly therapy spend |
97
+ | targetDate | 3-months, 6-months, 1-year, no-rush | 4 | #6, 1.92 |
98
+ | specific | one, few, ongoing | 3 | gates the date |
99
+ | gender | woman, man, non-binary, self-described, prefer-not-to-say | 21 | works in wellness (6/7) |
100
+ | remembering | nothing, notes-app, journal, voice-memos, other-app | 15 | tried before (#13) |
101
+ | recall, breakthrough, reexplain, midweek, pattern, retention | as listed | 9–25 | problem size (#4) |
102
+
103
+ ## 6. Claims to verify
104
+
105
+ - "Writing down what you learned right after a session helps it stick."
106
+ - "Most of what we hear is gone within a day." (the forgetting curve)
107
+ - "A lot of therapy's work happens between sessions."
108
+
109
+ ## 7. The last screen
110
+
111
+ "Make every session count." → https://apps.apple.com/app/id6760877491
112
+
113
+ ## 8. What the answers are for
114
+
115
+ They predict who pays and let the team build audiences on them once they reach
116
+ Superwall. They are not, by themselves, a reason to change the paywall: that
117
+ needs a test that shows the best paywall differs by answer.