@wazir-dev/cli 1.0.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 (629) hide show
  1. package/AGENTS.md +111 -0
  2. package/CHANGELOG.md +14 -0
  3. package/CONTRIBUTING.md +101 -0
  4. package/LICENSE +21 -0
  5. package/README.md +314 -0
  6. package/assets/composition-engine.mmd +34 -0
  7. package/assets/demo-script.sh +17 -0
  8. package/assets/logo-dark.svg +14 -0
  9. package/assets/logo.svg +14 -0
  10. package/assets/pipeline.mmd +39 -0
  11. package/assets/record-demo.sh +51 -0
  12. package/docs/README.md +51 -0
  13. package/docs/adapters/context-mode.md +60 -0
  14. package/docs/concepts/architecture.md +87 -0
  15. package/docs/concepts/artifact-model.md +60 -0
  16. package/docs/concepts/composition-engine.md +36 -0
  17. package/docs/concepts/indexing-and-recall.md +160 -0
  18. package/docs/concepts/observability.md +41 -0
  19. package/docs/concepts/roles-and-workflows.md +59 -0
  20. package/docs/concepts/terminology-policy.md +27 -0
  21. package/docs/getting-started/01-installation.md +78 -0
  22. package/docs/getting-started/02-first-run.md +102 -0
  23. package/docs/getting-started/03-adding-to-project.md +15 -0
  24. package/docs/getting-started/04-host-setup.md +15 -0
  25. package/docs/guides/ci-integration.md +15 -0
  26. package/docs/guides/creating-skills.md +15 -0
  27. package/docs/guides/expertise-module-authoring.md +15 -0
  28. package/docs/guides/hook-development.md +15 -0
  29. package/docs/guides/memory-and-learnings.md +34 -0
  30. package/docs/guides/multi-host-export.md +15 -0
  31. package/docs/guides/troubleshooting.md +101 -0
  32. package/docs/guides/writing-custom-roles.md +15 -0
  33. package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
  34. package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
  35. package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
  36. package/docs/readmes/INDEX.md +99 -0
  37. package/docs/readmes/features/expertise/README.md +171 -0
  38. package/docs/readmes/features/exports/README.md +222 -0
  39. package/docs/readmes/features/hooks/README.md +103 -0
  40. package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
  41. package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
  42. package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
  43. package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
  44. package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
  45. package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
  46. package/docs/readmes/features/hooks/session-start.md +119 -0
  47. package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
  48. package/docs/readmes/features/roles/README.md +157 -0
  49. package/docs/readmes/features/roles/clarifier.md +152 -0
  50. package/docs/readmes/features/roles/content-author.md +190 -0
  51. package/docs/readmes/features/roles/designer.md +193 -0
  52. package/docs/readmes/features/roles/executor.md +184 -0
  53. package/docs/readmes/features/roles/learner.md +210 -0
  54. package/docs/readmes/features/roles/planner.md +182 -0
  55. package/docs/readmes/features/roles/researcher.md +164 -0
  56. package/docs/readmes/features/roles/reviewer.md +184 -0
  57. package/docs/readmes/features/roles/specifier.md +162 -0
  58. package/docs/readmes/features/roles/verifier.md +215 -0
  59. package/docs/readmes/features/schemas/README.md +178 -0
  60. package/docs/readmes/features/skills/README.md +63 -0
  61. package/docs/readmes/features/skills/brainstorming.md +96 -0
  62. package/docs/readmes/features/skills/debugging.md +148 -0
  63. package/docs/readmes/features/skills/design.md +120 -0
  64. package/docs/readmes/features/skills/prepare-next.md +109 -0
  65. package/docs/readmes/features/skills/run-audit.md +159 -0
  66. package/docs/readmes/features/skills/scan-project.md +109 -0
  67. package/docs/readmes/features/skills/self-audit.md +176 -0
  68. package/docs/readmes/features/skills/tdd.md +137 -0
  69. package/docs/readmes/features/skills/using-skills.md +92 -0
  70. package/docs/readmes/features/skills/verification.md +120 -0
  71. package/docs/readmes/features/skills/writing-plans.md +104 -0
  72. package/docs/readmes/features/tooling/README.md +320 -0
  73. package/docs/readmes/features/workflows/README.md +186 -0
  74. package/docs/readmes/features/workflows/author.md +181 -0
  75. package/docs/readmes/features/workflows/clarify.md +154 -0
  76. package/docs/readmes/features/workflows/design-review.md +171 -0
  77. package/docs/readmes/features/workflows/design.md +169 -0
  78. package/docs/readmes/features/workflows/discover.md +162 -0
  79. package/docs/readmes/features/workflows/execute.md +173 -0
  80. package/docs/readmes/features/workflows/learn.md +167 -0
  81. package/docs/readmes/features/workflows/plan-review.md +165 -0
  82. package/docs/readmes/features/workflows/plan.md +170 -0
  83. package/docs/readmes/features/workflows/prepare-next.md +167 -0
  84. package/docs/readmes/features/workflows/review.md +169 -0
  85. package/docs/readmes/features/workflows/run-audit.md +191 -0
  86. package/docs/readmes/features/workflows/spec-challenge.md +159 -0
  87. package/docs/readmes/features/workflows/specify.md +160 -0
  88. package/docs/readmes/features/workflows/verify.md +177 -0
  89. package/docs/readmes/packages/README.md +50 -0
  90. package/docs/readmes/packages/ajv.md +117 -0
  91. package/docs/readmes/packages/context-mode.md +118 -0
  92. package/docs/readmes/packages/gray-matter.md +116 -0
  93. package/docs/readmes/packages/node-test.md +137 -0
  94. package/docs/readmes/packages/yaml.md +112 -0
  95. package/docs/reference/configuration-reference.md +159 -0
  96. package/docs/reference/expertise-index.md +52 -0
  97. package/docs/reference/git-flow.md +43 -0
  98. package/docs/reference/hooks.md +87 -0
  99. package/docs/reference/host-exports.md +50 -0
  100. package/docs/reference/launch-checklist.md +172 -0
  101. package/docs/reference/marketplace-listings.md +76 -0
  102. package/docs/reference/release-process.md +34 -0
  103. package/docs/reference/roles-reference.md +77 -0
  104. package/docs/reference/skills.md +33 -0
  105. package/docs/reference/templates.md +29 -0
  106. package/docs/reference/tooling-cli.md +94 -0
  107. package/docs/truth-claims.yaml +222 -0
  108. package/expertise/PROGRESS.md +63 -0
  109. package/expertise/README.md +18 -0
  110. package/expertise/antipatterns/PROGRESS.md +56 -0
  111. package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
  112. package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
  113. package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
  114. package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
  115. package/expertise/antipatterns/backend/index.md +24 -0
  116. package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
  117. package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
  118. package/expertise/antipatterns/code/async-antipatterns.md +622 -0
  119. package/expertise/antipatterns/code/code-smells.md +1186 -0
  120. package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
  121. package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
  122. package/expertise/antipatterns/code/index.md +27 -0
  123. package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
  124. package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
  125. package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
  126. package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
  127. package/expertise/antipatterns/design/dark-patterns.md +1121 -0
  128. package/expertise/antipatterns/design/index.md +22 -0
  129. package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
  130. package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
  131. package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
  132. package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
  133. package/expertise/antipatterns/frontend/index.md +23 -0
  134. package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
  135. package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
  136. package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
  137. package/expertise/antipatterns/index.md +31 -0
  138. package/expertise/antipatterns/performance/index.md +20 -0
  139. package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
  140. package/expertise/antipatterns/performance/premature-optimization.md +623 -0
  141. package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
  142. package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
  143. package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
  144. package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
  145. package/expertise/antipatterns/process/index.md +23 -0
  146. package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
  147. package/expertise/antipatterns/security/index.md +20 -0
  148. package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
  149. package/expertise/antipatterns/security/security-theater.md +843 -0
  150. package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
  151. package/expertise/architecture/PROGRESS.md +70 -0
  152. package/expertise/architecture/data/caching-architecture.md +671 -0
  153. package/expertise/architecture/data/data-consistency.md +574 -0
  154. package/expertise/architecture/data/data-modeling.md +536 -0
  155. package/expertise/architecture/data/event-streams-and-queues.md +634 -0
  156. package/expertise/architecture/data/index.md +25 -0
  157. package/expertise/architecture/data/search-architecture.md +663 -0
  158. package/expertise/architecture/data/sql-vs-nosql.md +708 -0
  159. package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
  160. package/expertise/architecture/decisions/build-vs-buy.md +616 -0
  161. package/expertise/architecture/decisions/index.md +23 -0
  162. package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
  163. package/expertise/architecture/decisions/technology-selection.md +616 -0
  164. package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
  165. package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
  166. package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
  167. package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
  168. package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
  169. package/expertise/architecture/distributed/index.md +25 -0
  170. package/expertise/architecture/distributed/saga-pattern.md +797 -0
  171. package/expertise/architecture/foundations/architectural-thinking.md +460 -0
  172. package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
  173. package/expertise/architecture/foundations/design-principles-solid.md +649 -0
  174. package/expertise/architecture/foundations/domain-driven-design.md +719 -0
  175. package/expertise/architecture/foundations/index.md +25 -0
  176. package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
  177. package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
  178. package/expertise/architecture/index.md +34 -0
  179. package/expertise/architecture/integration/api-design-graphql.md +638 -0
  180. package/expertise/architecture/integration/api-design-grpc.md +804 -0
  181. package/expertise/architecture/integration/api-design-rest.md +892 -0
  182. package/expertise/architecture/integration/index.md +25 -0
  183. package/expertise/architecture/integration/third-party-integration.md +795 -0
  184. package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
  185. package/expertise/architecture/integration/websockets-realtime.md +791 -0
  186. package/expertise/architecture/mobile-architecture/index.md +22 -0
  187. package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
  188. package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
  189. package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
  190. package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
  191. package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
  192. package/expertise/architecture/patterns/event-driven.md +797 -0
  193. package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
  194. package/expertise/architecture/patterns/index.md +27 -0
  195. package/expertise/architecture/patterns/layered-architecture.md +736 -0
  196. package/expertise/architecture/patterns/microservices.md +753 -0
  197. package/expertise/architecture/patterns/modular-monolith.md +692 -0
  198. package/expertise/architecture/patterns/monolith.md +626 -0
  199. package/expertise/architecture/patterns/plugin-architecture.md +735 -0
  200. package/expertise/architecture/patterns/serverless.md +780 -0
  201. package/expertise/architecture/scaling/database-scaling.md +615 -0
  202. package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
  203. package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
  204. package/expertise/architecture/scaling/index.md +24 -0
  205. package/expertise/architecture/scaling/multi-tenancy.md +800 -0
  206. package/expertise/architecture/scaling/stateless-design.md +787 -0
  207. package/expertise/backend/embedded-firmware.md +625 -0
  208. package/expertise/backend/go.md +853 -0
  209. package/expertise/backend/index.md +24 -0
  210. package/expertise/backend/java-spring.md +448 -0
  211. package/expertise/backend/node-typescript.md +625 -0
  212. package/expertise/backend/python-fastapi.md +724 -0
  213. package/expertise/backend/rust.md +458 -0
  214. package/expertise/backend/solidity.md +711 -0
  215. package/expertise/composition-map.yaml +443 -0
  216. package/expertise/content/foundations/content-modeling.md +395 -0
  217. package/expertise/content/foundations/editorial-standards.md +449 -0
  218. package/expertise/content/foundations/index.md +24 -0
  219. package/expertise/content/foundations/microcopy.md +455 -0
  220. package/expertise/content/foundations/terminology-governance.md +509 -0
  221. package/expertise/content/index.md +34 -0
  222. package/expertise/content/patterns/accessibility-copy.md +518 -0
  223. package/expertise/content/patterns/index.md +24 -0
  224. package/expertise/content/patterns/notification-content.md +433 -0
  225. package/expertise/content/patterns/sample-content.md +486 -0
  226. package/expertise/content/patterns/state-copy.md +439 -0
  227. package/expertise/design/PROGRESS.md +58 -0
  228. package/expertise/design/disciplines/dark-mode-theming.md +577 -0
  229. package/expertise/design/disciplines/design-systems.md +595 -0
  230. package/expertise/design/disciplines/index.md +25 -0
  231. package/expertise/design/disciplines/information-architecture.md +800 -0
  232. package/expertise/design/disciplines/interaction-design.md +788 -0
  233. package/expertise/design/disciplines/responsive-design.md +552 -0
  234. package/expertise/design/disciplines/usability-testing.md +516 -0
  235. package/expertise/design/disciplines/user-research.md +792 -0
  236. package/expertise/design/foundations/accessibility-design.md +796 -0
  237. package/expertise/design/foundations/color-theory.md +797 -0
  238. package/expertise/design/foundations/iconography.md +795 -0
  239. package/expertise/design/foundations/index.md +26 -0
  240. package/expertise/design/foundations/motion-and-animation.md +653 -0
  241. package/expertise/design/foundations/rtl-design.md +585 -0
  242. package/expertise/design/foundations/spacing-and-layout.md +607 -0
  243. package/expertise/design/foundations/typography.md +800 -0
  244. package/expertise/design/foundations/visual-hierarchy.md +761 -0
  245. package/expertise/design/index.md +32 -0
  246. package/expertise/design/patterns/authentication-flows.md +474 -0
  247. package/expertise/design/patterns/content-consumption.md +789 -0
  248. package/expertise/design/patterns/data-display.md +618 -0
  249. package/expertise/design/patterns/e-commerce.md +1494 -0
  250. package/expertise/design/patterns/feedback-and-states.md +642 -0
  251. package/expertise/design/patterns/forms-and-input.md +819 -0
  252. package/expertise/design/patterns/gamification.md +801 -0
  253. package/expertise/design/patterns/index.md +31 -0
  254. package/expertise/design/patterns/microinteractions.md +449 -0
  255. package/expertise/design/patterns/navigation.md +800 -0
  256. package/expertise/design/patterns/notifications.md +705 -0
  257. package/expertise/design/patterns/onboarding.md +700 -0
  258. package/expertise/design/patterns/search-and-filter.md +601 -0
  259. package/expertise/design/patterns/settings-and-preferences.md +768 -0
  260. package/expertise/design/patterns/social-and-community.md +748 -0
  261. package/expertise/design/platforms/desktop-native.md +612 -0
  262. package/expertise/design/platforms/index.md +25 -0
  263. package/expertise/design/platforms/mobile-android.md +825 -0
  264. package/expertise/design/platforms/mobile-cross-platform.md +983 -0
  265. package/expertise/design/platforms/mobile-ios.md +699 -0
  266. package/expertise/design/platforms/tablet.md +794 -0
  267. package/expertise/design/platforms/web-dashboard.md +790 -0
  268. package/expertise/design/platforms/web-responsive.md +550 -0
  269. package/expertise/design/psychology/behavioral-nudges.md +449 -0
  270. package/expertise/design/psychology/cognitive-load.md +1191 -0
  271. package/expertise/design/psychology/error-psychology.md +778 -0
  272. package/expertise/design/psychology/index.md +22 -0
  273. package/expertise/design/psychology/persuasive-design.md +736 -0
  274. package/expertise/design/psychology/user-mental-models.md +623 -0
  275. package/expertise/design/tooling/open-pencil.md +266 -0
  276. package/expertise/frontend/angular.md +1073 -0
  277. package/expertise/frontend/desktop-electron.md +546 -0
  278. package/expertise/frontend/flutter.md +782 -0
  279. package/expertise/frontend/index.md +27 -0
  280. package/expertise/frontend/native-android.md +409 -0
  281. package/expertise/frontend/native-ios.md +490 -0
  282. package/expertise/frontend/react-native.md +1160 -0
  283. package/expertise/frontend/react.md +808 -0
  284. package/expertise/frontend/vue.md +1089 -0
  285. package/expertise/humanize/domain-rules-code.md +79 -0
  286. package/expertise/humanize/domain-rules-content.md +67 -0
  287. package/expertise/humanize/domain-rules-technical-docs.md +56 -0
  288. package/expertise/humanize/index.md +35 -0
  289. package/expertise/humanize/self-audit-checklist.md +87 -0
  290. package/expertise/humanize/sentence-patterns.md +218 -0
  291. package/expertise/humanize/vocabulary-blacklist.md +105 -0
  292. package/expertise/i18n/PROGRESS.md +65 -0
  293. package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
  294. package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
  295. package/expertise/i18n/advanced/complex-scripts.md +30 -0
  296. package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
  297. package/expertise/i18n/advanced/testing-i18n.md +28 -0
  298. package/expertise/i18n/content/content-adaptation.md +23 -0
  299. package/expertise/i18n/content/locale-specific-formatting.md +23 -0
  300. package/expertise/i18n/content/machine-translation-integration.md +28 -0
  301. package/expertise/i18n/content/translation-management.md +29 -0
  302. package/expertise/i18n/foundations/date-time-calendars.md +67 -0
  303. package/expertise/i18n/foundations/i18n-architecture.md +272 -0
  304. package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
  305. package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
  306. package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
  307. package/expertise/i18n/foundations/string-externalization.md +236 -0
  308. package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
  309. package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
  310. package/expertise/i18n/index.md +38 -0
  311. package/expertise/i18n/platform/backend-i18n.md +31 -0
  312. package/expertise/i18n/platform/flutter-i18n.md +148 -0
  313. package/expertise/i18n/platform/native-android-i18n.md +36 -0
  314. package/expertise/i18n/platform/native-ios-i18n.md +36 -0
  315. package/expertise/i18n/platform/react-i18n.md +103 -0
  316. package/expertise/i18n/platform/web-css-i18n.md +81 -0
  317. package/expertise/i18n/rtl/arabic-specific.md +175 -0
  318. package/expertise/i18n/rtl/hebrew-specific.md +149 -0
  319. package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
  320. package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
  321. package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
  322. package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
  323. package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
  324. package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
  325. package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
  326. package/expertise/i18n/rtl/rtl-typography.md +160 -0
  327. package/expertise/index.md +113 -0
  328. package/expertise/index.yaml +216 -0
  329. package/expertise/infrastructure/cloud-aws.md +597 -0
  330. package/expertise/infrastructure/cloud-gcp.md +599 -0
  331. package/expertise/infrastructure/cybersecurity.md +816 -0
  332. package/expertise/infrastructure/database-mongodb.md +447 -0
  333. package/expertise/infrastructure/database-postgres.md +400 -0
  334. package/expertise/infrastructure/devops-cicd.md +787 -0
  335. package/expertise/infrastructure/index.md +27 -0
  336. package/expertise/performance/PROGRESS.md +50 -0
  337. package/expertise/performance/backend/api-latency.md +1204 -0
  338. package/expertise/performance/backend/background-jobs.md +506 -0
  339. package/expertise/performance/backend/connection-pooling.md +1209 -0
  340. package/expertise/performance/backend/database-query-optimization.md +515 -0
  341. package/expertise/performance/backend/index.md +23 -0
  342. package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
  343. package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
  344. package/expertise/performance/foundations/caching-strategies.md +489 -0
  345. package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
  346. package/expertise/performance/foundations/index.md +24 -0
  347. package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
  348. package/expertise/performance/foundations/memory-management.md +964 -0
  349. package/expertise/performance/foundations/performance-budgets.md +1314 -0
  350. package/expertise/performance/index.md +31 -0
  351. package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
  352. package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
  353. package/expertise/performance/infrastructure/index.md +22 -0
  354. package/expertise/performance/infrastructure/load-balancing.md +1081 -0
  355. package/expertise/performance/infrastructure/observability.md +1079 -0
  356. package/expertise/performance/mobile/index.md +23 -0
  357. package/expertise/performance/mobile/mobile-animations.md +544 -0
  358. package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
  359. package/expertise/performance/mobile/mobile-network.md +452 -0
  360. package/expertise/performance/mobile/mobile-rendering.md +599 -0
  361. package/expertise/performance/mobile/mobile-startup-time.md +505 -0
  362. package/expertise/performance/platform-specific/flutter-performance.md +647 -0
  363. package/expertise/performance/platform-specific/index.md +22 -0
  364. package/expertise/performance/platform-specific/node-performance.md +1307 -0
  365. package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
  366. package/expertise/performance/platform-specific/react-performance.md +1403 -0
  367. package/expertise/performance/web/bundle-optimization.md +1239 -0
  368. package/expertise/performance/web/image-and-media.md +636 -0
  369. package/expertise/performance/web/index.md +24 -0
  370. package/expertise/performance/web/network-optimization.md +1133 -0
  371. package/expertise/performance/web/rendering-performance.md +1098 -0
  372. package/expertise/performance/web/ssr-and-hydration.md +918 -0
  373. package/expertise/performance/web/web-vitals.md +1374 -0
  374. package/expertise/quality/accessibility.md +985 -0
  375. package/expertise/quality/evidence-based-verification.md +499 -0
  376. package/expertise/quality/index.md +24 -0
  377. package/expertise/quality/ml-model-audit.md +614 -0
  378. package/expertise/quality/performance.md +600 -0
  379. package/expertise/quality/testing-api.md +891 -0
  380. package/expertise/quality/testing-mobile.md +496 -0
  381. package/expertise/quality/testing-web.md +849 -0
  382. package/expertise/security/PROGRESS.md +54 -0
  383. package/expertise/security/agentic-identity.md +540 -0
  384. package/expertise/security/compliance-frameworks.md +601 -0
  385. package/expertise/security/data/data-encryption.md +364 -0
  386. package/expertise/security/data/data-privacy-gdpr.md +692 -0
  387. package/expertise/security/data/database-security.md +1171 -0
  388. package/expertise/security/data/index.md +22 -0
  389. package/expertise/security/data/pii-handling.md +531 -0
  390. package/expertise/security/foundations/authentication.md +1041 -0
  391. package/expertise/security/foundations/authorization.md +603 -0
  392. package/expertise/security/foundations/cryptography.md +1001 -0
  393. package/expertise/security/foundations/index.md +25 -0
  394. package/expertise/security/foundations/owasp-top-10.md +1354 -0
  395. package/expertise/security/foundations/secrets-management.md +1217 -0
  396. package/expertise/security/foundations/secure-sdlc.md +700 -0
  397. package/expertise/security/foundations/supply-chain-security.md +698 -0
  398. package/expertise/security/index.md +31 -0
  399. package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
  400. package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
  401. package/expertise/security/infrastructure/container-security.md +721 -0
  402. package/expertise/security/infrastructure/incident-response.md +1295 -0
  403. package/expertise/security/infrastructure/index.md +24 -0
  404. package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
  405. package/expertise/security/infrastructure/network-security.md +1337 -0
  406. package/expertise/security/mobile/index.md +23 -0
  407. package/expertise/security/mobile/mobile-android-security.md +1218 -0
  408. package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
  409. package/expertise/security/mobile/mobile-data-storage.md +1265 -0
  410. package/expertise/security/mobile/mobile-ios-security.md +1401 -0
  411. package/expertise/security/mobile/mobile-network-security.md +1520 -0
  412. package/expertise/security/smart-contract-security.md +594 -0
  413. package/expertise/security/testing/index.md +22 -0
  414. package/expertise/security/testing/penetration-testing.md +1258 -0
  415. package/expertise/security/testing/security-code-review.md +1765 -0
  416. package/expertise/security/testing/threat-modeling.md +1074 -0
  417. package/expertise/security/testing/vulnerability-scanning.md +1062 -0
  418. package/expertise/security/web/api-security.md +586 -0
  419. package/expertise/security/web/cors-and-headers.md +433 -0
  420. package/expertise/security/web/csrf.md +562 -0
  421. package/expertise/security/web/file-upload.md +1477 -0
  422. package/expertise/security/web/index.md +25 -0
  423. package/expertise/security/web/injection.md +1375 -0
  424. package/expertise/security/web/session-management.md +1101 -0
  425. package/expertise/security/web/xss.md +1158 -0
  426. package/exports/README.md +17 -0
  427. package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
  428. package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
  429. package/exports/hosts/claude/.claude/agents/designer.md +55 -0
  430. package/exports/hosts/claude/.claude/agents/executor.md +55 -0
  431. package/exports/hosts/claude/.claude/agents/learner.md +51 -0
  432. package/exports/hosts/claude/.claude/agents/planner.md +53 -0
  433. package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
  434. package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
  435. package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
  436. package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
  437. package/exports/hosts/claude/.claude/commands/author.md +42 -0
  438. package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
  439. package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
  440. package/exports/hosts/claude/.claude/commands/design.md +44 -0
  441. package/exports/hosts/claude/.claude/commands/discover.md +37 -0
  442. package/exports/hosts/claude/.claude/commands/execute.md +48 -0
  443. package/exports/hosts/claude/.claude/commands/learn.md +38 -0
  444. package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
  445. package/exports/hosts/claude/.claude/commands/plan.md +39 -0
  446. package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
  447. package/exports/hosts/claude/.claude/commands/review.md +40 -0
  448. package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
  449. package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
  450. package/exports/hosts/claude/.claude/commands/specify.md +38 -0
  451. package/exports/hosts/claude/.claude/commands/verify.md +37 -0
  452. package/exports/hosts/claude/.claude/settings.json +34 -0
  453. package/exports/hosts/claude/CLAUDE.md +19 -0
  454. package/exports/hosts/claude/export.manifest.json +38 -0
  455. package/exports/hosts/claude/host-package.json +67 -0
  456. package/exports/hosts/codex/AGENTS.md +19 -0
  457. package/exports/hosts/codex/export.manifest.json +38 -0
  458. package/exports/hosts/codex/host-package.json +41 -0
  459. package/exports/hosts/cursor/.cursor/hooks.json +16 -0
  460. package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
  461. package/exports/hosts/cursor/export.manifest.json +38 -0
  462. package/exports/hosts/cursor/host-package.json +42 -0
  463. package/exports/hosts/gemini/GEMINI.md +19 -0
  464. package/exports/hosts/gemini/export.manifest.json +38 -0
  465. package/exports/hosts/gemini/host-package.json +41 -0
  466. package/hooks/README.md +18 -0
  467. package/hooks/definitions/loop_cap_guard.yaml +21 -0
  468. package/hooks/definitions/post_tool_capture.yaml +24 -0
  469. package/hooks/definitions/pre_compact_summary.yaml +19 -0
  470. package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
  471. package/hooks/definitions/protected_path_write_guard.yaml +19 -0
  472. package/hooks/definitions/session_start.yaml +19 -0
  473. package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
  474. package/hooks/loop-cap-guard +17 -0
  475. package/hooks/post-tool-lint +36 -0
  476. package/hooks/protected-path-write-guard +17 -0
  477. package/hooks/session-start +41 -0
  478. package/llms-full.txt +2355 -0
  479. package/llms.txt +43 -0
  480. package/package.json +79 -0
  481. package/roles/README.md +20 -0
  482. package/roles/clarifier.md +42 -0
  483. package/roles/content-author.md +63 -0
  484. package/roles/designer.md +55 -0
  485. package/roles/executor.md +55 -0
  486. package/roles/learner.md +51 -0
  487. package/roles/planner.md +53 -0
  488. package/roles/researcher.md +43 -0
  489. package/roles/reviewer.md +54 -0
  490. package/roles/specifier.md +47 -0
  491. package/roles/verifier.md +71 -0
  492. package/schemas/README.md +24 -0
  493. package/schemas/accepted-learning.schema.json +20 -0
  494. package/schemas/author-artifact.schema.json +156 -0
  495. package/schemas/clarification.schema.json +19 -0
  496. package/schemas/design-artifact.schema.json +80 -0
  497. package/schemas/docs-claim.schema.json +18 -0
  498. package/schemas/export-manifest.schema.json +20 -0
  499. package/schemas/hook.schema.json +67 -0
  500. package/schemas/host-export-package.schema.json +18 -0
  501. package/schemas/implementation-plan.schema.json +19 -0
  502. package/schemas/proposed-learning.schema.json +19 -0
  503. package/schemas/research.schema.json +18 -0
  504. package/schemas/review.schema.json +29 -0
  505. package/schemas/run-manifest.schema.json +18 -0
  506. package/schemas/spec-challenge.schema.json +18 -0
  507. package/schemas/spec.schema.json +20 -0
  508. package/schemas/usage.schema.json +102 -0
  509. package/schemas/verification-proof.schema.json +29 -0
  510. package/schemas/wazir-manifest.schema.json +173 -0
  511. package/skills/README.md +40 -0
  512. package/skills/brainstorming/SKILL.md +77 -0
  513. package/skills/debugging/SKILL.md +50 -0
  514. package/skills/design/SKILL.md +61 -0
  515. package/skills/dispatching-parallel-agents/SKILL.md +128 -0
  516. package/skills/executing-plans/SKILL.md +70 -0
  517. package/skills/finishing-a-development-branch/SKILL.md +169 -0
  518. package/skills/humanize/SKILL.md +123 -0
  519. package/skills/init-pipeline/SKILL.md +124 -0
  520. package/skills/prepare-next/SKILL.md +20 -0
  521. package/skills/receiving-code-review/SKILL.md +123 -0
  522. package/skills/requesting-code-review/SKILL.md +105 -0
  523. package/skills/requesting-code-review/code-reviewer.md +108 -0
  524. package/skills/run-audit/SKILL.md +197 -0
  525. package/skills/scan-project/SKILL.md +41 -0
  526. package/skills/self-audit/SKILL.md +153 -0
  527. package/skills/subagent-driven-development/SKILL.md +154 -0
  528. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  529. package/skills/subagent-driven-development/implementer-prompt.md +102 -0
  530. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  531. package/skills/tdd/SKILL.md +23 -0
  532. package/skills/using-git-worktrees/SKILL.md +163 -0
  533. package/skills/using-skills/SKILL.md +95 -0
  534. package/skills/verification/SKILL.md +22 -0
  535. package/skills/wazir/SKILL.md +463 -0
  536. package/skills/writing-plans/SKILL.md +30 -0
  537. package/skills/writing-skills/SKILL.md +157 -0
  538. package/skills/writing-skills/anthropic-best-practices.md +122 -0
  539. package/skills/writing-skills/persuasion-principles.md +50 -0
  540. package/templates/README.md +20 -0
  541. package/templates/artifacts/README.md +10 -0
  542. package/templates/artifacts/accepted-learning.md +19 -0
  543. package/templates/artifacts/accepted-learning.template.json +12 -0
  544. package/templates/artifacts/author.md +74 -0
  545. package/templates/artifacts/author.template.json +19 -0
  546. package/templates/artifacts/clarification.md +21 -0
  547. package/templates/artifacts/clarification.template.json +12 -0
  548. package/templates/artifacts/execute-notes.md +19 -0
  549. package/templates/artifacts/implementation-plan.md +21 -0
  550. package/templates/artifacts/implementation-plan.template.json +11 -0
  551. package/templates/artifacts/learning-proposal.md +19 -0
  552. package/templates/artifacts/next-run-handoff.md +21 -0
  553. package/templates/artifacts/plan-review.md +19 -0
  554. package/templates/artifacts/proposed-learning.template.json +12 -0
  555. package/templates/artifacts/research.md +21 -0
  556. package/templates/artifacts/research.template.json +12 -0
  557. package/templates/artifacts/review-findings.md +19 -0
  558. package/templates/artifacts/review.template.json +11 -0
  559. package/templates/artifacts/run-manifest.template.json +8 -0
  560. package/templates/artifacts/spec-challenge.md +19 -0
  561. package/templates/artifacts/spec-challenge.template.json +11 -0
  562. package/templates/artifacts/spec.md +21 -0
  563. package/templates/artifacts/spec.template.json +12 -0
  564. package/templates/artifacts/verification-proof.md +19 -0
  565. package/templates/artifacts/verification-proof.template.json +11 -0
  566. package/templates/examples/accepted-learning.example.json +14 -0
  567. package/templates/examples/author.example.json +152 -0
  568. package/templates/examples/clarification.example.json +15 -0
  569. package/templates/examples/docs-claim.example.json +8 -0
  570. package/templates/examples/export-manifest.example.json +7 -0
  571. package/templates/examples/host-export-package.example.json +11 -0
  572. package/templates/examples/implementation-plan.example.json +17 -0
  573. package/templates/examples/proposed-learning.example.json +13 -0
  574. package/templates/examples/research.example.json +15 -0
  575. package/templates/examples/research.example.md +6 -0
  576. package/templates/examples/review.example.json +17 -0
  577. package/templates/examples/run-manifest.example.json +9 -0
  578. package/templates/examples/spec-challenge.example.json +14 -0
  579. package/templates/examples/spec.example.json +21 -0
  580. package/templates/examples/verification-proof.example.json +21 -0
  581. package/templates/examples/wazir-manifest.example.yaml +65 -0
  582. package/templates/task-definition-schema.md +99 -0
  583. package/tooling/README.md +20 -0
  584. package/tooling/src/adapters/context-mode.js +50 -0
  585. package/tooling/src/capture/command.js +376 -0
  586. package/tooling/src/capture/store.js +99 -0
  587. package/tooling/src/capture/usage.js +270 -0
  588. package/tooling/src/checks/branches.js +50 -0
  589. package/tooling/src/checks/brand-truth.js +110 -0
  590. package/tooling/src/checks/changelog.js +231 -0
  591. package/tooling/src/checks/command-registry.js +36 -0
  592. package/tooling/src/checks/commits.js +102 -0
  593. package/tooling/src/checks/docs-drift.js +103 -0
  594. package/tooling/src/checks/docs-truth.js +201 -0
  595. package/tooling/src/checks/runtime-surface.js +156 -0
  596. package/tooling/src/cli.js +116 -0
  597. package/tooling/src/command-options.js +56 -0
  598. package/tooling/src/commands/validate.js +320 -0
  599. package/tooling/src/doctor/command.js +91 -0
  600. package/tooling/src/export/command.js +77 -0
  601. package/tooling/src/export/compiler.js +498 -0
  602. package/tooling/src/guards/loop-cap-guard.js +52 -0
  603. package/tooling/src/guards/protected-path-write-guard.js +67 -0
  604. package/tooling/src/index/command.js +152 -0
  605. package/tooling/src/index/storage.js +1061 -0
  606. package/tooling/src/index/summarizers.js +261 -0
  607. package/tooling/src/loaders.js +18 -0
  608. package/tooling/src/project-root.js +22 -0
  609. package/tooling/src/recall/command.js +225 -0
  610. package/tooling/src/schema-validator.js +30 -0
  611. package/tooling/src/state-root.js +40 -0
  612. package/tooling/src/status/command.js +71 -0
  613. package/wazir.manifest.yaml +135 -0
  614. package/workflows/README.md +19 -0
  615. package/workflows/author.md +42 -0
  616. package/workflows/clarify.md +38 -0
  617. package/workflows/design-review.md +46 -0
  618. package/workflows/design.md +44 -0
  619. package/workflows/discover.md +37 -0
  620. package/workflows/execute.md +48 -0
  621. package/workflows/learn.md +38 -0
  622. package/workflows/plan-review.md +42 -0
  623. package/workflows/plan.md +39 -0
  624. package/workflows/prepare-next.md +37 -0
  625. package/workflows/review.md +40 -0
  626. package/workflows/run-audit.md +41 -0
  627. package/workflows/spec-challenge.md +41 -0
  628. package/workflows/specify.md +38 -0
  629. package/workflows/verify.md +37 -0
@@ -0,0 +1,736 @@
1
+ # Persuasive Design — Expertise Module
2
+
3
+ > A persuasive design specialist applies behavioral psychology, cognitive bias research, and ethical influence frameworks to guide users toward beneficial actions without manipulation. The scope spans Cialdini's principles of influence, the Fogg Behavior Model, nudge theory, cognitive biases (loss aversion, anchoring, default effect, endowment effect, peak-end rule), ethical measurement, dark pattern identification and avoidance, and platform-specific persuasion considerations. The line between persuasion and manipulation is the central ethical tension of this discipline.
4
+
5
+ ---
6
+
7
+ ## 1. The Science of Persuasion
8
+
9
+ ### 1.1 Cialdini's Principles of Influence
10
+
11
+ Dr. Robert Cialdini's research, first published in *Influence: The Psychology of Persuasion* (1984) and expanded in *Pre-Suasion* (2016) and *Influence, New and Expanded* (2021), identifies seven principles that govern how humans are persuaded. The original six principles remain the most widely applied in design; the seventh (Unity) was added in 2021.
12
+
13
+ **Principle 1 — Reciprocity**
14
+ Humans feel obligated to return favors. When someone gives us something — a gift, a concession, information — we experience psychological pressure to reciprocate. This is deeply wired: anthropological studies show reciprocity norms exist in every known human culture.
15
+
16
+ Design relevance: Free trials, free content, generous onboarding experiences, and value-first interactions all trigger reciprocity. The key ethical constraint is that the value must be genuine, not a manufactured sense of obligation.
17
+
18
+ **Principle 2 — Commitment and Consistency**
19
+ Once we make a choice, take a stand, or invest effort, we feel internal pressure to behave consistently with that commitment. This operates at the level of self-identity — inconsistency creates cognitive dissonance, which is psychologically uncomfortable.
20
+
21
+ Design relevance: Progressive onboarding, saved progress indicators, streak counters, and micro-commitments (small initial actions that lead to larger ones) all leverage this principle. The "foot-in-the-door" technique — starting with a small request before escalating — is a classic application.
22
+
23
+ **Principle 3 — Social Proof**
24
+ When uncertain, people look to the behavior of similar others as a guide for their own actions. The more people undertaking an action, the more we consider that action correct. This is strongest when the "others" are perceived as similar to us.
25
+
26
+ Design relevance: Reviews, ratings, testimonials, "X people are viewing this," usage statistics, and case studies all function as social proof. The specificity and credibility of social proof matters — "Join 2 million users" is less persuasive than "Used by 847 design teams including Spotify and Airbnb."
27
+
28
+ **Principle 4 — Authority**
29
+ People defer to experts and those perceived as holding legitimate authority. Authority cues include credentials, uniforms, titles, and demonstrated expertise. Trust transfers from the authority figure to the message.
30
+
31
+ Design relevance: Expert endorsements, certifications, professional design and branding, "as featured in" logos, and content authored by credentialed professionals all leverage authority. The ethical line: authority must be genuine, not fabricated.
32
+
33
+ **Principle 5 — Liking**
34
+ We are more easily persuaded by people and brands we like. Liking is driven by similarity (shared values, background), physical attractiveness, compliments, familiarity (mere exposure effect), and association with positive things.
35
+
36
+ Design relevance: Brand personality, conversational UI copy, personalization ("Welcome back, Sarah"), aesthetically pleasing design, and community-building features all leverage liking. People also like those who cooperate with them toward mutual goals — positioning the product as an ally, not a gatekeeper.
37
+
38
+ **Principle 6 — Scarcity**
39
+ People assign more value to opportunities that are less available. Scarcity operates through two mechanisms: limited quantity ("Only 3 left") and limited time ("Offer ends in 2 hours"). Loss aversion amplifies scarcity — the fear of missing out outweighs the anticipated pleasure of obtaining.
40
+
41
+ Design relevance: Limited-time offers, countdown timers, inventory indicators, exclusive access, and waitlists. Critical ethical constraint: scarcity signals must be truthful. Fabricated urgency (fake countdown timers that reset, artificial stock limitations) is a dark pattern.
42
+
43
+ **Principle 7 — Unity**
44
+ Added in 2021, Unity describes the persuasive power of shared identity. When people perceive someone as "one of us" — through family, ethnicity, nationality, political affiliation, professional community, or shared experience — they are far more open to influence.
45
+
46
+ Design relevance: Community features, "built by developers for developers" positioning, shared mission statements, and user communities organized around identity. Unity goes beyond liking — it is about belonging.
47
+
48
+ ### 1.2 The Fogg Behavior Model (B=MAT)
49
+
50
+ BJ Fogg, founder of the Behavior Design Lab at Stanford, proposed that behavior occurs when three elements converge simultaneously:
51
+
52
+ ```
53
+ B = M x A x T
54
+
55
+ B = Behavior (the target action)
56
+ M = Motivation (desire to perform the action)
57
+ A = Ability (ease of performing the action)
58
+ T = Trigger/Prompt (the cue that initiates action)
59
+ ```
60
+
61
+ If any element is absent or insufficient, the behavior does not occur.
62
+
63
+ **Motivation** operates along three axes:
64
+ - Pleasure / Pain — immediate sensory or emotional response
65
+ - Hope / Fear — anticipation of future outcomes
66
+ - Social acceptance / Social rejection — desire for belonging
67
+
68
+ **Ability** is determined by six simplicity factors:
69
+ - Time — how long it takes
70
+ - Money — the financial cost
71
+ - Physical effort — how much exertion is required
72
+ - Brain cycles — cognitive load required
73
+ - Social deviance — whether the behavior violates social norms
74
+ - Non-routine — how much it departs from established habits
75
+
76
+ The most effective design strategy is usually to increase Ability (make it easier) rather than to increase Motivation (make them want it more). Motivation is volatile; simplicity is reliable.
77
+
78
+ **Triggers (Prompts)** come in three types:
79
+ - **Spark** — for high-ability, low-motivation situations. The prompt itself carries motivational content (an inspiring message, a fear-based alert). Example: "Your account security is at risk — enable 2FA now."
80
+ - **Facilitator** — for high-motivation, low-ability situations. The prompt makes the action easier. Example: "Enable 2FA with one tap" (with pre-filled settings).
81
+ - **Signal** — for high-motivation, high-ability situations. A simple reminder suffices. Example: a notification badge.
82
+
83
+ **The Action Line**: Fogg's model includes a curved "action line" on a graph with Motivation on the Y-axis and Ability on the X-axis. Behaviors above the line occur when triggered; behaviors below the line do not. High motivation compensates for low ability, and vice versa — but the relationship is not linear.
84
+
85
+ ### 1.3 Nudge Theory
86
+
87
+ Richard Thaler and Cass Sunstein introduced Nudge Theory in their 2008 book *Nudge: Improving Decisions About Health, Wealth, and Happiness*. Thaler received the Nobel Prize in Economics in 2017 for his contributions to behavioral economics.
88
+
89
+ **Core concept**: A nudge is any aspect of the **choice architecture** that alters people's behavior in a predictable way without forbidding any options or significantly changing economic incentives. To count as a nudge, the intervention must be easy and cheap to avoid.
90
+
91
+ **Libertarian paternalism**: Thaler and Sunstein's framework for ethical nudging. "Libertarian" because choices are preserved — no options are removed. "Paternalism" because the choice architecture is designed to steer people toward outcomes that improve their welfare, as judged by themselves.
92
+
93
+ **Choice architecture** encompasses:
94
+ - Default options (the most powerful nudge)
95
+ - Number and arrangement of options
96
+ - Framing of choices
97
+ - Feedback mechanisms
98
+ - Mapping between choices and outcomes
99
+ - Error tolerance in the system
100
+
101
+ ### 1.4 Key Cognitive Biases in Design
102
+
103
+ **Loss Aversion** (Kahneman & Tversky, 1979)
104
+ People feel losses approximately twice as intensely as equivalent gains. Losing $100 feels roughly twice as painful as gaining $100 feels pleasurable. This asymmetry profoundly shapes decision-making.
105
+
106
+ Design applications:
107
+ - "Don't lose your progress" is more motivating than "Save your progress"
108
+ - Free trial expiration warnings leverage fear of losing access
109
+ - Feature comparison showing what users miss on lower tiers
110
+ - Progress bars that would be "lost" if the user abandons a flow
111
+
112
+ Ethical boundary: Loss aversion should highlight genuine value at risk, not manufacture artificial fears.
113
+
114
+ **Anchoring** (Tversky & Kahneman, 1974)
115
+ The first piece of information encountered (the "anchor") disproportionately influences subsequent judgments. In pricing, the first number seen sets expectations for all subsequent numbers.
116
+
117
+ Design applications:
118
+ - Presenting the premium plan first makes the standard plan feel like a bargain
119
+ - Showing original price crossed out next to sale price
120
+ - "Compare at $299" messaging
121
+ - Starting a donation form with higher suggested amounts
122
+
123
+ Ethical boundary: Anchors must reference real values. A "was $999, now $99" anchor is deceptive if the product was never actually sold at $999.
124
+
125
+ **Default Effect** (Johnson & Goldstein, 2003)
126
+ People overwhelmingly stick with pre-selected options. The most cited evidence: organ donation rates. In countries with opt-out defaults (presumed consent), donation rates exceed 90%. In opt-in countries, rates hover around 15%.
127
+
128
+ Design applications:
129
+ - Pre-selecting recommended options in forms
130
+ - Default privacy settings
131
+ - Pre-checked newsletter subscriptions (ethically contested)
132
+ - Default shipping methods, payment plans
133
+
134
+ Ethical boundary: Defaults should align with the user's likely preference and best interest. Pre-checking "share my data with partners" exploits the default effect and likely violates GDPR requirements for affirmative consent.
135
+
136
+ **Endowment Effect** (Thaler, 1980)
137
+ People value things more highly once they feel ownership over them. In experiments, people demand roughly twice as much to give up an object they own compared to what they would pay to acquire the same object.
138
+
139
+ Design applications:
140
+ - Free trials that let users customize and invest time before payment
141
+ - "Your workspace" language establishing psychological ownership
142
+ - Avatar and profile customization during onboarding
143
+ - Saving user-generated content that would be lost without subscription
144
+
145
+ The endowment effect works in concert with loss aversion: once users feel they own something (their data, their customizations, their history), losing it triggers loss aversion.
146
+
147
+ **Peak-End Rule** (Kahneman, 1993)
148
+ People judge an experience primarily based on how they felt at its most intense point (the peak) and at its end, rather than on the sum or average of every moment. Duration has remarkably little effect on remembered experience.
149
+
150
+ Design applications:
151
+ - Delightful moments at key points in the user journey (animations, celebrations, rewards)
152
+ - Ensuring the final step of any flow is positive (success screens, confirmation messages, thank-you pages)
153
+ - Post-purchase experience matters as much as pre-purchase
154
+ - Error recovery that ends on a positive note
155
+
156
+ The peak-end rule explains why a 30-minute experience with one delightful moment and a satisfying conclusion is remembered more favorably than a 30-minute experience that was consistently pleasant but ended abruptly.
157
+
158
+ ---
159
+
160
+ ## 2. Design Implications — 15 Rules for Ethical Persuasion
161
+
162
+ Each rule is tied to its underlying psychological principle, stated as an actionable directive, and illustrated with a concrete example.
163
+
164
+ ### Rule 1: Use Social Proof Truthfully and Specifically
165
+
166
+ **Principle**: Social Proof (Cialdini)
167
+ **Rule**: Display genuine usage data, real testimonials with attribution, and verifiable statistics. Specificity increases credibility. Never fabricate or inflate numbers.
168
+ **Example**: Slack's growth-stage homepage showed "Used by 750,000+ organizations including IBM, Oracle, and Airbnb" with real logos. This combined social proof with authority. Compare the weak alternative: "Trusted by millions" (vague, unverifiable).
169
+
170
+ ### Rule 2: Show Progress to Leverage Commitment
171
+
172
+ **Principle**: Commitment and Consistency (Cialdini)
173
+ **Rule**: Make invested effort visible. Show progress bars, completion percentages, and streaks. Once users see what they have built, consistency bias motivates continuation.
174
+ **Example**: LinkedIn's profile completeness meter ("Your profile is 70% complete — add a photo to reach All-Star status") drives completion through commitment. Users who have filled out 70% feel compelled to finish. Duolingo's streak counter leverages the same principle — breaking a 45-day streak triggers loss aversion layered on top of commitment.
175
+
176
+ ### Rule 3: Provide Sensible Defaults That Serve the User
177
+
178
+ **Principle**: Default Effect (Thaler & Sunstein)
179
+ **Rule**: Set defaults to the option most users would choose if they were informed and attentive. Never use defaults to extract value from user inattention.
180
+ **Example**: A privacy settings page that defaults to "Share usage analytics (anonymized)" while defaulting "Share data with third-party advertisers" to off. The first serves legitimate product improvement; the second would exploit inattention. Google's Android permissions model shifted from install-time blanket permissions (exploitative default) to runtime individual permission requests (ethical default).
181
+
182
+ ### Rule 4: Use Anchoring for Honest Price Framing
183
+
184
+ **Principle**: Anchoring (Tversky & Kahneman)
185
+ **Rule**: Present pricing tiers from highest to lowest so that the recommended plan feels like good value. The anchor must reference a real price. Highlight the recommended tier visually.
186
+ **Example**: Basecamp shows a single price ($299/month flat, unlimited users) and anchors it against the typical per-seat SaaS cost: "Most tools charge $10-20/seat. At 20 users, that is $200-400/month." The anchor is truthful and helps users evaluate value.
187
+
188
+ ### Rule 5: Leverage Loss Aversion for Feature Adoption, Not Fear
189
+
190
+ **Principle**: Loss Aversion (Kahneman & Tversky)
191
+ **Rule**: Frame feature adoption in terms of what users will miss without it, but only when the missed value is genuine. Never manufacture artificial threats.
192
+ **Example**: Dropbox's storage warning ("You are 90% full — upgrade to avoid losing the ability to sync new files") is ethical because the consequence is real. Contrast with a dark pattern: "Your data may be at risk!" when no actual risk exists.
193
+
194
+ ### Rule 6: Use Scarcity Honestly
195
+
196
+ **Principle**: Scarcity (Cialdini)
197
+ **Rule**: Only display scarcity indicators when scarcity is genuine. Countdown timers must reflect real deadlines. Inventory counts must reflect real inventory. Fabricated urgency erodes trust and may violate consumer protection law.
198
+ **Example**: Booking.com's "Only 2 rooms left at this price" is legitimate when tied to real inventory data. However, if the counter resets when the user returns, or if "2 rooms" reflects artificially constrained allocation rather than actual availability, it crosses into deception.
199
+
200
+ ### Rule 7: Reduce Friction at the Moment of Motivation
201
+
202
+ **Principle**: Fogg Behavior Model (B=MAT) — Ability
203
+ **Rule**: When motivation peaks (after reading a compelling case study, after a successful trial moment), minimize the steps required to act. Every additional click, field, or page load bleeds conversion.
204
+ **Example**: After a user completes their first successful project in a project management tool, show a single-button upgrade prompt: "Keep building — upgrade now" with one-click purchase using saved payment info. Do not redirect to a pricing page with 47 plan comparisons.
205
+
206
+ ### Rule 8: Match Triggers to Motivation-Ability State
207
+
208
+ **Principle**: Fogg Behavior Model — Trigger Types
209
+ **Rule**: Use sparks when motivation is low, facilitators when ability is low, and signals when both are high. Mismatched triggers waste attention and breed annoyance.
210
+ **Example**: A fitness app sending a push notification at 7 AM to a user who has never exercised in the morning needs a spark ("Morning workouts boost focus by 20% — try a 5-minute routine?"), not a signal ("Time to work out!"). For a user who works out every morning but finds the app confusing, a facilitator is needed ("Tap here to start your usual routine").
211
+
212
+ ### Rule 9: Leverage Reciprocity by Leading with Value
213
+
214
+ **Principle**: Reciprocity (Cialdini)
215
+ **Rule**: Give genuine value before asking for anything. Free tools, educational content, and generous trial periods create authentic reciprocity. The value must be useful independent of whether the user converts.
216
+ **Example**: HubSpot offers a free CRM with no time limit, free courses through HubSpot Academy, and free website grading tools. Users who receive genuine value feel natural reciprocity when evaluating paid tiers. Contrast with "Download our free e-book" that gates a 3-page PDF behind a 12-field form — that triggers resentment, not reciprocity.
217
+
218
+ ### Rule 10: Build Liking Through Genuine Brand Personality
219
+
220
+ **Principle**: Liking (Cialdini)
221
+ **Rule**: Develop an authentic, consistent brand voice. Use conversational microcopy. Show the humans behind the product. Personalize greetings and communications. Do not fake familiarity.
222
+ **Example**: Mailchimp's brand voice — friendly, slightly irreverent, never condescending — creates liking. Their high-five animation after sending a campaign creates a peak moment (peak-end rule) layered on liking. The error page "Something went wrong. We are looking into it" with a hand-drawn illustration humanizes the experience.
223
+
224
+ ### Rule 11: Establish Authority Through Demonstrated Expertise
225
+
226
+ **Principle**: Authority (Cialdini)
227
+ **Rule**: Show credentials, certifications, media mentions, and expert endorsements. Publish substantive content that demonstrates genuine expertise. Never fabricate authority signals.
228
+ **Example**: Stripe's developer documentation is so thorough that it functions as authority-building content marketing. Their engineering blog posts about infrastructure at scale demonstrate genuine expertise that transfers trust to the payment product. Security certifications (SOC 2, PCI DSS) displayed on the checkout page leverage authority at the moment of financial commitment.
229
+
230
+ ### Rule 12: Create Peak Moments at Critical Journey Points
231
+
232
+ **Principle**: Peak-End Rule (Kahneman)
233
+ **Rule**: Identify the 3-5 most critical moments in the user journey and invest disproportionate design effort there. Ensure every flow ends positively.
234
+ **Example**: After a user publishes their first blog post on a CMS, show a celebratory animation with confetti, a shareable preview, and a "Your first post!" badge. This peak moment anchors the memory of the entire onboarding experience. Conversely, a checkout flow that ends with a bare "Order #48291 confirmed" text page wastes the peak-end opportunity.
235
+
236
+ ### Rule 13: Use the Endowment Effect Through Earned Customization
237
+
238
+ **Principle**: Endowment Effect (Thaler)
239
+ **Rule**: Let users invest in personalization before requiring commitment. Once they have customized their workspace, curated their preferences, or built something, they value it more and are less likely to abandon.
240
+ **Example**: Notion allows extensive workspace setup — custom databases, templates, workflows — during a free plan. When users consider switching to a competitor, the endowment effect makes their invested customization feel too valuable to abandon. The switching cost is psychological, not contractual.
241
+
242
+ ### Rule 14: Frame Choices, Do Not Remove Them
243
+
244
+ **Principle**: Nudge Theory — Libertarian Paternalism (Thaler & Sunstein)
245
+ **Rule**: Guide users toward good choices through framing, defaults, and emphasis, but never remove the ability to choose differently. The "right" choice should be easiest, but alternatives must remain accessible.
246
+ **Example**: A cookie consent banner that makes "Accept necessary only" equally prominent as "Accept all" nudges toward privacy without removing choice. Compare the dark pattern: a large green "Accept all" button with a tiny gray "Manage preferences" link that leads to a 4-screen flow.
247
+
248
+ ### Rule 15: Design for the User's Future Self
249
+
250
+ **Principle**: Nudge Theory — Temporal Discounting
251
+ **Rule**: Help users make decisions their future selves will thank them for. Present future consequences concretely. Bridge the empathy gap between present and future self.
252
+ **Example**: A retirement savings app that shows a photo-aged version of the user alongside projected retirement income makes the future self concrete and present. A simpler application: a subscription page showing "That is $3.25/week" reframes a $169/year commitment into a more digestible present-moment anchor.
253
+
254
+ ---
255
+
256
+ ## 3. Measurement and Metrics
257
+
258
+ ### 3.1 Conversion Funnels
259
+
260
+ A conversion funnel maps the sequential steps from initial awareness to target action. Each step has a measurable drop-off rate. Persuasive design improvements are measured by their impact on these drop-offs.
261
+
262
+ **Standard Funnel Stages:**
263
+ ```
264
+ Awareness --> Interest --> Consideration --> Intent --> Action --> Retention
265
+ 100% 60% 35% 20% 8% 3%
266
+ ```
267
+
268
+ **Measuring Persuasive Elements in the Funnel:**
269
+ - Identify the highest-drop-off stage
270
+ - Hypothesize which persuasive principle could reduce the drop-off
271
+ - Implement and A/B test the change
272
+ - Measure not just the target stage but downstream effects
273
+
274
+ Example funnel analysis:
275
+ ```
276
+ Landing page visitors: 10,000
277
+ Clicked "Start free trial": 1,200 (12% CTR)
278
+ Completed signup form: 480 (40% form completion)
279
+ Activated (first key action): 144 (30% activation)
280
+ Converted to paid: 36 (25% conversion)
281
+ Still active at 90 days: 22 (61% retention)
282
+ ```
283
+
284
+ The biggest lever here is the 40% form completion rate. Applying Fogg's Ability principle (reduce fields, add social login, defer non-essential fields) could move this to 65%, cascading improvements through the entire funnel.
285
+
286
+ ### 3.2 A/B Testing Persuasive Elements
287
+
288
+ **What to Test:**
289
+ - Social proof placement and specificity (Rule 1)
290
+ - Progress indicator presence and design (Rule 2)
291
+ - Default selections (Rule 3)
292
+ - Pricing page anchor order (Rule 4)
293
+ - Loss-framed vs. gain-framed copy (Rule 5)
294
+ - Scarcity indicator presence (Rule 6)
295
+ - Number of form fields at the motivation peak (Rule 7)
296
+ - Trigger type and timing (Rule 8)
297
+ - Value-first vs. ask-first onboarding (Rule 9)
298
+
299
+ **Testing Protocol:**
300
+ 1. Define a single primary metric (North Star) and 2-3 guardrail metrics
301
+ 2. Calculate required sample size for statistical significance (typically p < 0.05)
302
+ 3. Run the test for a minimum of one full business cycle (typically 1-2 weeks)
303
+ 4. Do not peek at results early — this inflates false positive rates
304
+ 5. Measure long-term retention, not just immediate conversion
305
+ 6. Document and share learnings regardless of outcome
306
+
307
+ **Common Pitfalls:**
308
+ - Testing too many variables simultaneously (use multivariate testing only with sufficient traffic)
309
+ - Optimizing for a vanity metric while degrading a meaningful one
310
+ - Stopping tests too early when results look promising ("peeking problem")
311
+ - Not segmenting results by user type (new vs. returning, mobile vs. desktop)
312
+
313
+ ### 3.3 Engagement Metrics
314
+
315
+ **Actionable Metrics** (measure real value):
316
+ - Activation rate: percentage of signups who complete a key action
317
+ - Time to value: duration from signup to first meaningful outcome
318
+ - Feature adoption rate: percentage of users who discover and use a feature
319
+ - Task success rate: percentage of users who accomplish their goal
320
+ - Retention cohorts: percentage of users active at 7/30/90 days, segmented by acquisition source
321
+ - Net Promoter Score (NPS): likelihood to recommend (tracks genuine satisfaction)
322
+ - Customer Effort Score (CES): how easy it was to accomplish a task
323
+ - Revenue per user: actual economic value generated
324
+
325
+ **Vanity Metrics** (look impressive but mislead):
326
+ - Total registered users (without active user count)
327
+ - Page views (without engagement depth)
328
+ - Total app downloads (without retention data)
329
+ - Time on site (high time can indicate confusion, not engagement)
330
+ - Social media followers (without engagement rate)
331
+ - Email list size (without open/click rates)
332
+
333
+ **The Vanity Metric Test**: Ask "Can this metric directly inform a design decision?" If no, it is likely vanity. A metric is actionable only if it changes what you do.
334
+
335
+ ### 3.4 Ethical Metrics vs. Vanity Metrics
336
+
337
+ Ethical measurement requires distinguishing between metrics that reflect genuine user value and metrics that can be inflated through manipulation.
338
+
339
+ **Ethical Metrics Framework:**
340
+
341
+ | Metric Category | Ethical Version | Manipulable Version |
342
+ |---|---|---|
343
+ | Engagement | Tasks completed successfully | Time spent on site |
344
+ | Growth | Organic referral rate | Total signups (including dark-pattern-driven) |
345
+ | Retention | 90-day active retention | "Retained" users who cannot figure out how to cancel |
346
+ | Revenue | Customer lifetime value | Revenue from users who forgot to cancel free trials |
347
+ | Satisfaction | CES (effort to accomplish goal) | Survey responses from self-selected happy users |
348
+
349
+ **Guardrail Metrics for Persuasive Design:**
350
+ When A/B testing persuasive elements, always track these guardrails alongside your primary metric:
351
+ - Support ticket volume (did the change cause confusion?)
352
+ - Cancellation rate (did short-term conversion come at long-term cost?)
353
+ - Refund rate (did users feel tricked after converting?)
354
+ - Social sentiment (are users complaining about the experience?)
355
+ - Regulatory complaints (are users reporting the practice?)
356
+
357
+ If a persuasive design change improves conversion but increases support tickets or cancellation rate, the change is likely crossing from persuasion into manipulation.
358
+
359
+ ---
360
+
361
+ ## 4. Dark Patterns Warning
362
+
363
+ **This section is critical.** Dark patterns represent the weaponization of the psychological principles described above. Every principle in this document can be used ethically or abusively. Understanding dark patterns is not optional knowledge for persuasive designers — it is a professional and increasingly legal obligation.
364
+
365
+ The term "dark patterns" was coined by UX researcher Harry Brignull in 2010 when he registered darkpatterns.org (now deceptive.design) as a pattern library to name and shame deceptive user interfaces. His 2023 book *Deceptive Patterns* provides the definitive taxonomy.
366
+
367
+ ### 4.1 Taxonomy of Dark Patterns
368
+
369
+ **Confirmshaming**
370
+ Manipulating users through guilt or shame when they decline an offer. The decline option is worded to make the user feel foolish or irresponsible.
371
+
372
+ Examples:
373
+ - "No thanks, I don't want to save money" (decline button for a coupon popup)
374
+ - "I prefer to stay uninformed" (decline button for a newsletter)
375
+ - "No, I enjoy paying full price" (decline button for a discount offer)
376
+
377
+ Why it is harmful: Confirmshaming weaponizes social pressure and self-image. It exploits the Liking principle in reverse — making users dislike themselves for a legitimate choice. It creates a hostile relationship between product and user.
378
+
379
+ **Roach Motel (Easy In, Hard Out)**
380
+ Making it easy to get into a situation (subscription, account, commitment) but deliberately difficult to get out.
381
+
382
+ Examples:
383
+ - One-click signup but 23-screen, 32-action cancellation flow (the FTC's allegation against Uber for Uber One cancellation)
384
+ - Gym memberships that require in-person cancellation or mailed certified letters
385
+ - Amazon's former "Iliad Flow" — a 4-page, 6-click, 15-option cancellation process that the FTC challenged in a case resulting in a $2.5 billion settlement (September 2025)
386
+
387
+ Why it is harmful: Directly exploits commitment bias and the endowment effect against the user's interests. Traps users through friction rather than value.
388
+
389
+ **Hidden Costs**
390
+ Revealing additional charges (service fees, shipping, taxes, "processing fees") only at the final stage of checkout, after the user has invested time and effort.
391
+
392
+ Examples:
393
+ - A concert ticket priced at $49.99 that becomes $78.50 at checkout after "service fee," "facility charge," and "order processing fee"
394
+ - A hotel booking that adds a "resort fee" on the final payment page
395
+ - Subscription services that advertise monthly rates but charge annually
396
+
397
+ Why it is harmful: Exploits commitment bias (sunk cost of time already spent) and anchoring (the original price sets expectations). Users feel trapped into completing a purchase they would not have started at the true price.
398
+
399
+ **Forced Continuity**
400
+ Automatically converting a free trial into a paid subscription without clear, timely notice, and making cancellation difficult.
401
+
402
+ Examples:
403
+ - Free trial requires credit card, converts to paid after 7 days with a single email notification sent at 3 AM
404
+ - Subscription that continues billing after cancellation "through the end of the billing period" but the billing period auto-renews before the cancellation takes effect
405
+ - Services that require calling a phone number during business hours to cancel
406
+
407
+ Why it is harmful: Exploits the default effect (continuing to charge is the default), loss aversion (users fear losing access to invested data), and the endowment effect (users have customized their experience during the trial).
408
+
409
+ **Trick Questions**
410
+ Using confusing language, double negatives, or misleading phrasing to cause users to select options they did not intend.
411
+
412
+ Examples:
413
+ - "Uncheck this box if you would prefer not to not receive promotional emails" (triple negative)
414
+ - A checkbox labeled "I agree to the Terms of Service" that also includes "and consent to share my data with third-party partners" in the same action
415
+ - Toggle switches where "on" means opting out
416
+
417
+ Why it is harmful: Exploits cognitive load limitations. Users scan interfaces quickly; trick questions punish normal reading behavior. This directly violates the informed consent requirements of GDPR and similar regulations.
418
+
419
+ **Privacy Zuckering**
420
+ Named after Meta CEO Mark Zuckerberg. Tricking users into sharing more personal information than they intended through confusing privacy settings, buried opt-outs, or default-on data sharing.
421
+
422
+ Examples:
423
+ - A 47-page privacy policy with sharing enabled by default and opt-out buried 5 levels deep in settings
424
+ - "Improve your experience" toggle that actually shares browsing data with advertisers
425
+ - Contact import features that send messages to imported contacts without clear consent
426
+ - Location sharing that defaults to "always" when "while using the app" would serve the stated purpose
427
+
428
+ Why it is harmful: Exploits the default effect, cognitive load limitations, and trust (authority principle). Users trust that a reputable company's defaults serve their interests.
429
+
430
+ **Friend Spam**
431
+ Requesting access to a user's contacts (email, phone, social media) under the guise of "finding friends" and then sending messages to those contacts without clear, informed consent.
432
+
433
+ Examples:
434
+ - LinkedIn's historic practice of importing contacts and sending repeated invitation emails
435
+ - Apps that request contact access for "finding friends" but send promotional messages
436
+ - "Invite friends to earn rewards" flows that pre-select all contacts
437
+
438
+ Why it is harmful: Exploits social proof and reciprocity against third parties who never consented. Damages the user's relationships and reputation.
439
+
440
+ **Disguised Ads**
441
+ Advertisements designed to look like content, navigation, or system interfaces so users click them without realizing they are ads.
442
+
443
+ Examples:
444
+ - "Download" buttons on software sites that are actually ads for unrelated software
445
+ - Sponsored search results styled identically to organic results
446
+ - Native advertising without clear "Sponsored" or "Ad" labeling
447
+ - "Recommended for you" sections mixing genuine recommendations with paid placements without distinction
448
+
449
+ Why it is harmful: Exploits trust and the authority of the platform. Users click believing they are interacting with the product, not an advertiser.
450
+
451
+ **Sneak into Basket**
452
+ Adding additional items, services, or insurance to a user's shopping cart without explicit action.
453
+
454
+ Examples:
455
+ - Pre-selected travel insurance during flight booking
456
+ - "Protection plans" auto-added to electronics purchases
457
+ - Charitable donations pre-added to checkout totals
458
+
459
+ Why it is harmful: Exploits the default effect and inattention. Users who review carefully can remove the items, but the practice profits from those who do not.
460
+
461
+ **Misdirection**
462
+ Using visual design, layout, or wording to draw attention toward one option (beneficial to the company) and away from another (beneficial to the user).
463
+
464
+ Examples:
465
+ - A large, brightly colored "Accept all cookies" button next to a small, gray, low-contrast "Manage preferences" link
466
+ - Upgrade prompts where "Maybe later" is styled as disabled/inactive
467
+ - Unsubscribe flows where "Keep my subscription" is prominent and "Continue canceling" is a text link
468
+
469
+ Why it is harmful: Exploits visual hierarchy and the brain's attention heuristics. The user's stated preference (to manage cookies, to cancel) is deliberately undermined through design.
470
+
471
+ **Bait and Switch**
472
+ Advertising one outcome but delivering another. The user intends to do one thing, but the interface causes a different, undesired outcome.
473
+
474
+ Examples:
475
+ - A "Close" button (X) on a popup that actually triggers a subscription instead of dismissing the popup
476
+ - Windows 10's historic upgrade prompt where clicking the X (traditionally "close/dismiss") initiated the upgrade
477
+ - "Free" tools that require payment after initial setup is complete
478
+
479
+ Why it is harmful: Directly violates user trust and intent. Exploits learned interface conventions against the user.
480
+
481
+ ### 4.2 Where the Ethical Line Is
482
+
483
+ The distinction between persuasion and manipulation rests on three tests:
484
+
485
+ **The Transparency Test**: Would the technique still work if the user fully understood what was happening? Social proof works even when users know they are being shown testimonials. Trick questions fail this test — they only work because users misunderstand.
486
+
487
+ **The Alignment Test**: Does the technique serve the user's genuine interests, or only the company's? Sensible defaults that save the user time serve both parties. Pre-checked "share my data" boxes serve only the company.
488
+
489
+ **The Reversibility Test**: Can the user easily undo the action? A free trial that is easy to cancel respects autonomy. A roach motel that requires 23 screens to cancel does not.
490
+
491
+ If a technique fails any of these three tests, it is likely a dark pattern.
492
+
493
+ **Spectrum of Intent:**
494
+ ```
495
+ Ethical Persuasion Gray Area Dark Pattern
496
+ |__________________________|__________________________|
497
+ Social proof Urgency messaging Fake scarcity
498
+ Sensible defaults Pre-selected upsells Sneak into basket
499
+ Progress indicators Streak anxiety Confirmshaming
500
+ Value-first trials Difficult cancellation Roach motel
501
+ Clear recommendations Anchoring to inflated Hidden costs
502
+ "original" prices
503
+ ```
504
+
505
+ ### 4.3 Legal Implications
506
+
507
+ The legal landscape around dark patterns has shifted dramatically since 2020. Designers who employ dark patterns expose their organizations to significant legal and financial risk.
508
+
509
+ **GDPR (EU — General Data Protection Regulation)**
510
+ - Article 7: Consent must be "freely given, specific, informed and unambiguous." Pre-checked boxes, bundled consent, and confusing language all violate this requirement.
511
+ - The European Data Protection Board (EDPB) published Guidelines 3/2022 specifically addressing dark patterns in social media platforms, categorizing them into: overloading, skipping, stirring, hindering, fickle, and left in the dark.
512
+ - Fines: up to 4% of global annual turnover or 20 million euros, whichever is higher.
513
+
514
+ **FTC (United States — Federal Trade Commission)**
515
+ - The FTC Act Section 5 prohibits "unfair or deceptive acts or practices in or affecting commerce."
516
+ - The FTC's Negative Option Rule (updated) targets subscription traps. Although the Eighth Circuit vacated the "Click-to-Cancel" rule in July 2025, the FTC restarted rulemaking in January 2026 and continues enforcement under existing authority (ROSCA and Section 5).
517
+ - Amazon settlement: $2.5 billion (September 2025) — the largest civil penalty in FTC history for dark patterns related to Prime subscription enrollment and cancellation.
518
+ - Uber complaint: Alleged 23-screen, 32-action cancellation flow for Uber One.
519
+ - Fortnite (Epic Games): $245 million refund order for dark patterns targeting children.
520
+ - The FTC has signaled that it considers dark patterns a top enforcement priority regardless of specific rulemaking outcomes.
521
+
522
+ **California (CPRA/CCPA)**
523
+ - The California Privacy Rights Act requires that "the path to exercising privacy controls should not be more difficult than the path to providing personal information."
524
+ - Symmetry in Choice requirement: opt-out must be as easy as opt-in.
525
+ - The California AG has taken enforcement action against companies using dark patterns in cookie consent.
526
+
527
+ **Digital Services Act (EU — DSA, effective February 2024)**
528
+ - Article 25 explicitly prohibits online platforms from designing interfaces that "deceive, manipulate, or otherwise materially distort or impair" users' ability to make autonomous decisions.
529
+ - This is the first major regulation to directly address dark patterns by name.
530
+
531
+ **India (Digital Personal Data Protection Act, 2023)**
532
+ - Section 8(5) prohibits obtaining consent through deceptive design patterns.
533
+ - Explicitly names dark patterns including false urgency, confirmshaming, forced action, and interface interference.
534
+
535
+ **Penalties Summary:**
536
+ | Jurisdiction | Maximum Penalty | Notable Enforcement |
537
+ |---|---|---|
538
+ | EU (GDPR) | 4% global turnover or 20M EUR | Multiple cookie consent actions |
539
+ | US (FTC) | Per-violation fines + restitution | Amazon $2.5B, Epic $245M |
540
+ | California | $7,500 per intentional violation | Cookie consent enforcement |
541
+ | EU (DSA) | 6% global turnover | Effective February 2024 |
542
+ | India | Up to 250 crore INR (~$30M) | Framework enacted 2023 |
543
+
544
+ ### 4.4 Organizational Responsibility
545
+
546
+ Dark patterns are rarely the work of a single rogue designer. They emerge from organizational incentives:
547
+ - When designers are measured solely on conversion rates
548
+ - When "growth hacking" culture rewards short-term metrics
549
+ - When legal review of UX flows is absent
550
+ - When A/B tests optimize only for revenue without guardrail metrics
551
+
552
+ **Prevention Measures:**
553
+ - Include ethical review in the design process (UX ethics checklist)
554
+ - Require cancellation flow testing as part of QA
555
+ - Track refund rates, support tickets, and social sentiment as guardrails
556
+ - Empower designers to flag and refuse dark pattern requests
557
+ - Conduct adversarial UX reviews: assign a team member to find ways the interface could be perceived as deceptive
558
+
559
+ ---
560
+
561
+ ## 5. Platform-Specific Considerations
562
+
563
+ ### 5.1 Mobile: Heightened Susceptibility
564
+
565
+ Mobile users are more susceptible to persuasive techniques for several structural reasons:
566
+
567
+ **Small Screen, Limited Context**
568
+ - Smaller screens display less information, making it harder to evaluate choices fully
569
+ - Users see one option at a time in many flows, reducing comparison ability
570
+ - Fine print and secondary options are harder to read and tap on small screens
571
+ - Interactive targets must be at least 44x44pt (Apple HIG) / 48x48dp (Material Design), but dark patterns exploit the minimum by making "decline" targets smaller
572
+
573
+ **Urgency and Interruption**
574
+ - Mobile devices are checked 80-150 times per day (average), creating habitual, reflexive interaction patterns
575
+ - Push notifications interrupt users in high-emotion, low-attention states
576
+ - The red badge notification (borrowed from Apple's unread count pattern) triggers urgency — studies show red color triggers the brain to perceive a sense of urgency
577
+ - Time-limited offers are more effective on mobile because users feel they cannot easily return to evaluate later
578
+
579
+ **Touch Interaction Vulnerabilities**
580
+ - "Fat finger" errors are common on mobile — accidental taps on ads, unwanted options, or dismiss buttons that actually confirm
581
+ - Swipe gestures can be ambiguous (does swiping dismiss or confirm?)
582
+ - Mobile keyboards create friction that makes form-heavy flows feel more burdensome, amplifying the Fogg Ability factor
583
+
584
+ **Mobile-Specific Ethical Guidelines:**
585
+ - Make decline/dismiss targets at least as large as accept targets
586
+ - Never auto-play video with sound on mobile
587
+ - Respect system-level Do Not Disturb settings
588
+ - Provide clear, one-tap unsubscribe from push notifications
589
+ - Test all persuasive flows on the smallest supported screen size
590
+
591
+ ### 5.2 Desktop: More Deliberate, Still Vulnerable
592
+
593
+ Desktop users typically have more screen real estate, more context visible simultaneously, and more deliberate interaction patterns. But desktop is not immune to persuasion.
594
+
595
+ **Desktop-Specific Characteristics:**
596
+ - Users can compare options side-by-side more easily — pricing pages and comparison tables are more effective on desktop
597
+ - Mouse hover states enable progressive disclosure of information
598
+ - Longer session times mean users engage more deeply with content-based persuasion (case studies, documentation, whitepapers)
599
+ - Multi-tab behavior means users are more likely to comparison-shop, making honest social proof and authority more important
600
+
601
+ **Desktop-Specific Persuasion Opportunities:**
602
+ - Complex pricing comparison tables with anchoring (present premium first)
603
+ - Detailed social proof (full case studies, video testimonials)
604
+ - Interactive product demos and calculators
605
+ - Chatbots and live chat for real-time persuasion at decision points
606
+ - Exit-intent overlays (ethically fraught — use sparingly, offer genuine value)
607
+
608
+ **Desktop-Specific Risks:**
609
+ - Exit-intent popups that use confirmshaming
610
+ - Cookie consent banners that use misdirection
611
+ - Complicated account deletion flows buried in settings
612
+ - Auto-playing videos that disrupt the browsing experience
613
+
614
+ ### 5.3 Push Notifications as Persuasion
615
+
616
+ Push notifications are among the most powerful and most abusable persuasive tools available to designers. They operate outside the product interface, interrupting users in their daily lives.
617
+
618
+ **Effective and Ethical Push Notification Design:**
619
+
620
+ Timing:
621
+ - Send notifications when the user is most likely to act (custom-timed notifications achieve 60%+ response rates vs. 6% for generic timing)
622
+ - Respect time zones and sleeping hours
623
+ - Never send notifications solely to re-engage churning users with artificial urgency
624
+
625
+ Content:
626
+ - Notifications should contain genuine value: real information, meaningful updates, time-sensitive and truthful alerts
627
+ - Use the Fogg trigger types: sparks for unmotivated users, facilitators for motivated-but-blocked users, signals for ready-to-act users
628
+ - Personalize based on actual user behavior, not demographic assumptions
629
+
630
+ Frequency:
631
+ - Notification fatigue sets in quickly — studies show diminishing returns after 2-5 notifications per week for most app categories
632
+ - Allow granular notification preferences (not just on/off)
633
+ - Track notification-driven uninstall rates as a guardrail metric
634
+
635
+ **Dark Patterns in Push Notifications:**
636
+ - Fake "message from a person" notifications (dating apps, social networks)
637
+ - FOMO-inducing notifications ("Your friends are using the app right now!")
638
+ - Notifications that cannot be disabled without disabling all app notifications
639
+ - Re-permission prompts that use confirmshaming ("Are you sure? You'll miss important updates!")
640
+ - Badge counts that include marketing messages alongside genuine notifications
641
+
642
+ **Platform Notification Guidelines:**
643
+ - iOS requires explicit notification permission (opt-in) — design the pre-permission prompt carefully, explaining genuine value
644
+ - Android 13+ also requires explicit notification permission
645
+ - Both platforms allow users to disable notifications per-app — respect this as a clear signal
646
+ - Web push notifications require explicit opt-in but are frequently requested too early, before the user understands the value
647
+
648
+ ---
649
+
650
+ ## 6. Quick Reference Checklist
651
+
652
+ Use this checklist during design reviews to evaluate persuasive elements for ethical compliance.
653
+
654
+ ### Transparency
655
+ - [ ] Would this technique still work if we explained it to the user?
656
+ - [ ] Is all pricing, availability, and urgency information truthful?
657
+ - [ ] Are social proof numbers real and verifiable?
658
+ - [ ] Are testimonials from real users with real attribution?
659
+ - [ ] Is the "original price" in any crossed-out pricing a real price that was charged?
660
+
661
+ ### User Autonomy
662
+ - [ ] Can the user easily reverse any action taken (cancel, unsubscribe, delete account)?
663
+ - [ ] Is the opt-out path as simple as the opt-in path?
664
+ - [ ] Are defaults set to serve the user's likely preference, not just business revenue?
665
+ - [ ] Are all options (including decline/dismiss) equally accessible and legible?
666
+ - [ ] Does the flow preserve all user choices without pre-selecting options that benefit only the company?
667
+
668
+ ### Consent Quality
669
+ - [ ] Is consent specific (not bundled with unrelated permissions)?
670
+ - [ ] Is consent language clear (no double negatives, no jargon)?
671
+ - [ ] Can the user withdraw consent as easily as granting it?
672
+ - [ ] Are pre-checked boxes limited to options that genuinely serve user interests?
673
+ - [ ] Does the consent mechanism meet GDPR/CCPA/applicable regulatory requirements?
674
+
675
+ ### Dark Pattern Scan
676
+ - [ ] No confirmshaming language in decline options?
677
+ - [ ] No hidden costs revealed only at final checkout?
678
+ - [ ] No forced continuity without clear, timely pre-charge notification?
679
+ - [ ] No trick questions or confusing double negatives?
680
+ - [ ] No sneak-into-basket (unrequested items added to cart)?
681
+ - [ ] No misdirection through asymmetric button styling for accept vs. decline?
682
+ - [ ] No friend spam (messaging contacts without explicit, informed consent)?
683
+ - [ ] No disguised ads (ads that look like content or UI elements)?
684
+ - [ ] No bait and switch (X/close buttons that trigger unwanted actions)?
685
+ - [ ] Cancellation flow requires no more steps than signup flow?
686
+
687
+ ### Measurement Integrity
688
+ - [ ] Primary success metric reflects genuine user value (not just revenue)?
689
+ - [ ] Guardrail metrics are tracked (support tickets, cancellation rate, refund rate)?
690
+ - [ ] A/B tests run for full business cycles with adequate sample sizes?
691
+ - [ ] Long-term retention is measured, not just immediate conversion?
692
+ - [ ] Vanity metrics are not used to justify design decisions?
693
+
694
+ ### Platform-Specific
695
+ - [ ] Mobile: Decline targets are at least as large as accept targets?
696
+ - [ ] Mobile: Push notifications contain genuine value and respect frequency limits?
697
+ - [ ] Mobile: Flows are tested on smallest supported screen?
698
+ - [ ] Desktop: Exit-intent overlays offer genuine value (not confirmshaming)?
699
+ - [ ] Notifications: Pre-permission prompt explains genuine benefit?
700
+ - [ ] Notifications: Users can adjust granular preferences (not just on/off)?
701
+
702
+ ### Legal Compliance
703
+ - [ ] Cookie consent meets GDPR/ePrivacy requirements (no pre-checked non-essential cookies)?
704
+ - [ ] Subscription cancellation meets FTC/ROSCA requirements (simple mechanism, clear disclosure)?
705
+ - [ ] Privacy controls meet CPRA symmetry-in-choice requirements?
706
+ - [ ] Children's interactions comply with COPPA (if applicable)?
707
+ - [ ] Dark pattern review is documented for regulatory defense?
708
+
709
+ ---
710
+
711
+ ## 7. Key References
712
+
713
+ ### Foundational Texts
714
+ - Cialdini, R.B. (2021). *Influence, New and Expanded: The Psychology of Persuasion*. Harper Business. — The definitive text on influence principles, updated with the seventh principle (Unity) and modern applications.
715
+ - Fogg, B.J. (2003). *Persuasive Technology: Using Computers to Change What We Think and Do*. Morgan Kaufmann. — Foundational work on captology (computers as persuasive technology).
716
+ - Fogg, B.J. (2009). "A Behavior Model for Persuasive Design." *Proceedings of the 4th International Conference on Persuasive Technology*. — The original B=MAT paper.
717
+ - Thaler, R.H. & Sunstein, C.R. (2008). *Nudge: Improving Decisions About Health, Wealth, and Happiness*. Yale University Press. — The foundational text on choice architecture and libertarian paternalism.
718
+ - Kahneman, D. (2011). *Thinking, Fast and Slow*. Farrar, Straus and Giroux. — Comprehensive coverage of cognitive biases including loss aversion, anchoring, and the peak-end rule.
719
+ - Brignull, H. (2023). *Deceptive Patterns: Exposing the Tricks Tech Companies Use to Control You*. Testimonium Ltd. — The definitive taxonomy of dark patterns from the researcher who coined the term.
720
+
721
+ ### Regulatory and Legal References
722
+ - European Data Protection Board, Guidelines 3/2022 on Dark Patterns in Social Media Platform Interfaces.
723
+ - FTC, "Bringing Dark Patterns to Light" (Staff Report, September 2022).
724
+ - EU Digital Services Act, Article 25 — Prohibition of Dark Patterns (effective February 2024).
725
+ - India Digital Personal Data Protection Act, 2023, Section 8(5).
726
+ - California Privacy Rights Act (CPRA), Symmetry in Choice provisions.
727
+
728
+ ### Online Resources
729
+ - Deceptive Design (deceptive.design, formerly darkpatterns.org) — Harry Brignull's pattern library and hall of shame.
730
+ - Behavior Design Lab, Stanford University (behaviordesign.stanford.edu) — BJ Fogg's research lab resources.
731
+ - Influence at Work (influenceatwork.com) — Dr. Cialdini's organization and training materials.
732
+ - Nielsen Norman Group (nngroup.com) — Evidence-based UX research including dark pattern analysis.
733
+
734
+ ---
735
+
736
+ *This module covers the psychology of persuasion as applied to digital product design. It is intended to equip designers with the knowledge to persuade ethically, measure honestly, recognize dark patterns, and comply with evolving legal requirements. The line between helpful guidance and harmful manipulation is not always obvious — which is precisely why this knowledge matters.*