agy-superpowers 5.0.7 → 5.0.9
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.
- package/package.json +1 -1
- package/template/agent/rules/superpowers.md +54 -0
- package/template/agent/skills/api-design/SKILL.md +193 -0
- package/template/agent/skills/app-store-optimizer/SKILL.md +127 -0
- package/template/agent/skills/auth-and-identity/SKILL.md +167 -0
- package/template/agent/skills/backend-developer/SKILL.md +148 -0
- package/template/agent/skills/community-manager/SKILL.md +115 -0
- package/template/agent/skills/content-marketer/SKILL.md +111 -0
- package/template/agent/skills/conversion-optimizer/SKILL.md +142 -0
- package/template/agent/skills/copywriter/SKILL.md +114 -0
- package/template/agent/skills/cto-architect/SKILL.md +133 -0
- package/template/agent/skills/customer-success-manager/SKILL.md +126 -0
- package/template/agent/skills/data-analyst/SKILL.md +147 -0
- package/template/agent/skills/devops-engineer/SKILL.md +117 -0
- package/template/agent/skills/email-infrastructure/SKILL.md +164 -0
- package/template/agent/skills/frontend-developer/SKILL.md +172 -0
- package/template/agent/skills/frontend-developer/references/react-nextjs.md +343 -0
- package/template/agent/skills/frontend-developer/references/react-rules/_sections.md +46 -0
- package/template/agent/skills/frontend-developer/references/react-rules/_template.md +28 -0
- package/template/agent/skills/frontend-developer/references/react-rules/advanced-event-handler-refs.md +55 -0
- package/template/agent/skills/frontend-developer/references/react-rules/advanced-init-once.md +42 -0
- package/template/agent/skills/frontend-developer/references/react-rules/advanced-use-latest.md +39 -0
- package/template/agent/skills/frontend-developer/references/react-rules/async-api-routes.md +38 -0
- package/template/agent/skills/frontend-developer/references/react-rules/async-defer-await.md +80 -0
- package/template/agent/skills/frontend-developer/references/react-rules/async-dependencies.md +51 -0
- package/template/agent/skills/frontend-developer/references/react-rules/async-parallel.md +28 -0
- package/template/agent/skills/frontend-developer/references/react-rules/async-suspense-boundaries.md +99 -0
- package/template/agent/skills/frontend-developer/references/react-rules/bundle-barrel-imports.md +59 -0
- package/template/agent/skills/frontend-developer/references/react-rules/bundle-conditional.md +31 -0
- package/template/agent/skills/frontend-developer/references/react-rules/bundle-defer-third-party.md +49 -0
- package/template/agent/skills/frontend-developer/references/react-rules/bundle-dynamic-imports.md +35 -0
- package/template/agent/skills/frontend-developer/references/react-rules/bundle-preload.md +50 -0
- package/template/agent/skills/frontend-developer/references/react-rules/client-event-listeners.md +74 -0
- package/template/agent/skills/frontend-developer/references/react-rules/client-localstorage-schema.md +71 -0
- package/template/agent/skills/frontend-developer/references/react-rules/client-passive-event-listeners.md +48 -0
- package/template/agent/skills/frontend-developer/references/react-rules/client-swr-dedup.md +56 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-batch-dom-css.md +107 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-cache-function-results.md +80 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-cache-property-access.md +28 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-cache-storage.md +70 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-combine-iterations.md +32 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-early-exit.md +50 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-flatmap-filter.md +60 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-hoist-regexp.md +45 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-index-maps.md +37 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-length-check-first.md +49 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-min-max-loop.md +82 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-set-map-lookups.md +24 -0
- package/template/agent/skills/frontend-developer/references/react-rules/js-tosorted-immutable.md +57 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-activity.md +26 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-animate-svg-wrapper.md +47 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-conditional-render.md +40 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-content-visibility.md +38 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-hoist-jsx.md +46 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-hydration-no-flicker.md +82 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-hydration-suppress-warning.md +30 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-resource-hints.md +85 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-script-defer-async.md +68 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-svg-precision.md +28 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rendering-usetransition-loading.md +75 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-defer-reads.md +39 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-dependencies.md +45 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-derived-state-no-effect.md +40 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-derived-state.md +29 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-functional-setstate.md +74 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-lazy-state-init.md +58 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-memo-with-default-value.md +38 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-memo.md +44 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-move-effect-to-event.md +45 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-no-inline-components.md +82 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-simple-expression-in-memo.md +35 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-split-combined-hooks.md +64 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-transitions.md +40 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-use-deferred-value.md +59 -0
- package/template/agent/skills/frontend-developer/references/react-rules/rerender-use-ref-transient-values.md +73 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-after-nonblocking.md +73 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-auth-actions.md +96 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-cache-lru.md +41 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-cache-react.md +76 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-dedup-props.md +65 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-hoist-static-io.md +142 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-parallel-fetching.md +83 -0
- package/template/agent/skills/frontend-developer/references/react-rules/server-serialization.md +38 -0
- package/template/agent/skills/frontend-developer/references/svelte-sveltekit.md +220 -0
- package/template/agent/skills/frontend-developer/references/vanilla.md +275 -0
- package/template/agent/skills/frontend-developer/references/vue-nuxt.md +289 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/_index.md +154 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/animation-class-based-technique.md +254 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/animation-state-driven-technique.md +291 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-async.md +97 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-data-flow.md +307 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-fallthrough-attrs.md +174 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-keep-alive.md +137 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-slots.md +216 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-suspense.md +228 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-teleport.md +108 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-transition-group.md +128 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/component-transition.md +125 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/composables.md +290 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/directives.md +162 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-avoid-component-abstraction-in-lists.md +159 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-v-once-v-memo-directives.md +182 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/perf-virtualize-large-lists.md +187 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/plugins.md +166 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/reactivity.md +344 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/render-functions.md +201 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/sfc.md +310 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/state-management.md +135 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/best-practices/updated-hook-performance.md +187 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/_index.md +23 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-beforeenter-no-param-trigger.md +167 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-beforerouteenter-no-this.md +176 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-guard-async-await-pattern.md +227 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-navigation-guard-infinite-loop.md +187 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-navigation-guard-next-deprecated.md +150 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-param-change-no-lifecycle.md +181 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-simple-routing-cleanup.md +209 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/router/router-use-vue-router-for-production.md +183 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/_index.md +29 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/async-component-testing.md +163 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/teleport-testing-complexity.md +158 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-async-await-flushpromises.md +175 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-browser-vs-node-runners.md +208 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-component-blackbox-approach.md +144 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-composables-helper-wrapper.md +238 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-e2e-playwright-recommended.md +242 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-no-snapshot-only.md +197 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-pinia-store-setup.md +228 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-suspense-async-components.md +229 -0
- package/template/agent/skills/frontend-developer/references/vue-rules/testing/testing-vitest-recommended-for-vue.md +204 -0
- package/template/agent/skills/game-design/SKILL.md +194 -0
- package/template/agent/skills/game-developer/SKILL.md +175 -0
- package/template/agent/skills/growth-hacker/SKILL.md +122 -0
- package/template/agent/skills/i18n-localization/SKILL.md +126 -0
- package/template/agent/skills/influencer-marketer/SKILL.md +141 -0
- package/template/agent/skills/mobile-developer/SKILL.md +194 -0
- package/template/agent/skills/mobile-developer/references/android-native.md +396 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-accessibility.md +36 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-architecture.md +52 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-coroutines.md +139 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-data-layer.md +51 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-emulator-skill.md +108 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-gradle-logic.md +126 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-retrofit.md +142 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-testing.md +102 -0
- package/template/agent/skills/mobile-developer/references/android-rules/android-viewmodel.md +43 -0
- package/template/agent/skills/mobile-developer/references/android-rules/coil-compose.md +74 -0
- package/template/agent/skills/mobile-developer/references/android-rules/compose-navigation.md +422 -0
- package/template/agent/skills/mobile-developer/references/android-rules/compose-performance-audit.md +199 -0
- package/template/agent/skills/mobile-developer/references/android-rules/compose-ui.md +49 -0
- package/template/agent/skills/mobile-developer/references/android-rules/gradle-build-performance.md +346 -0
- package/template/agent/skills/mobile-developer/references/android-rules/kotlin-concurrency-expert.md +169 -0
- package/template/agent/skills/mobile-developer/references/android-rules/rxjava-to-coroutines-migration.md +101 -0
- package/template/agent/skills/mobile-developer/references/android-rules/xml-to-compose-migration.md +338 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-best-practices.md +52 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-checks-migration.md +134 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-cli-app-best-practices.md +123 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-doc-validation.md +45 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-matcher-best-practices.md +106 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-modern-features.md +241 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-package-maintenance.md +75 -0
- package/template/agent/skills/mobile-developer/references/flutter-rules/dart-test-fundamentals.md +124 -0
- package/template/agent/skills/mobile-developer/references/flutter.md +291 -0
- package/template/agent/skills/mobile-developer/references/ios-native.md +358 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/accessibility-patterns.md +215 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/animation-advanced.md +403 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/animation-basics.md +284 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/animation-transitions.md +326 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/charts-accessibility.md +135 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/charts.md +602 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/image-optimization.md +203 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/latest-apis.md +464 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/layout-best-practices.md +266 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/liquid-glass.md +416 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/list-patterns.md +394 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/macos-scenes.md +318 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/macos-views.md +357 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/macos-window-styling.md +303 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/performance-patterns.md +403 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/scroll-patterns.md +293 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/sheet-navigation-patterns.md +363 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/state-management.md +417 -0
- package/template/agent/skills/mobile-developer/references/ios-rules/view-structure.md +389 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/_sections.md +86 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/_template.md +28 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/animation-derived-value.md +53 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/animation-gesture-detector-press.md +95 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/animation-gpu-properties.md +65 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/design-system-compound-components.md +66 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/fonts-config-plugin.md +71 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/imports-design-system-folder.md +68 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/js-hoist-intl.md +61 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-callbacks.md +44 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-function-references.md +132 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-images.md +53 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-inline-objects.md +97 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-item-expensive.md +94 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-item-memo.md +82 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-item-types.md +104 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/list-performance-virtualize.md +67 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/monorepo-native-deps-in-app.md +46 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/monorepo-single-dependency-versions.md +63 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/navigation-native-navigators.md +188 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/react-compiler-destructure-functions.md +50 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/react-compiler-reanimated-shared-values.md +48 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/react-state-dispatcher.md +91 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/react-state-fallback.md +56 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/react-state-minimize.md +65 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/rendering-no-falsy-and.md +74 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/rendering-text-in-text-component.md +36 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/scroll-position-no-state.md +82 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/state-ground-truth.md +80 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-expo-image.md +66 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-image-gallery.md +104 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-measure-views.md +78 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-menus.md +174 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-native-modals.md +77 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-pressable.md +61 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-safe-area-scroll.md +65 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-scrollview-content-inset.md +45 -0
- package/template/agent/skills/mobile-developer/references/react-native-rules/ui-styling.md +87 -0
- package/template/agent/skills/mobile-developer/references/react-native.md +345 -0
- package/template/agent/skills/monetization-strategist/SKILL.md +119 -0
- package/template/agent/skills/paid-acquisition-specialist/SKILL.md +119 -0
- package/template/agent/skills/product-manager/SKILL.md +105 -0
- package/template/agent/skills/real-time-features/SKILL.md +194 -0
- package/template/agent/skills/retention-specialist/SKILL.md +123 -0
- package/template/agent/skills/saas-architect/SKILL.md +139 -0
- package/template/agent/skills/security-engineer/SKILL.md +133 -0
- package/template/agent/skills/seo-specialist/SKILL.md +130 -0
- package/template/agent/skills/subscription-billing/SKILL.md +179 -0
- package/template/agent/skills/ux-designer/SKILL.md +128 -0
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: game-design
|
|
3
|
+
description: Use when designing game mechanics, core loops, progression systems, monetization for games, difficulty curves, tutorial design, or player psychology
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Game Design Lens
|
|
7
|
+
|
|
8
|
+
> **Philosophy:** Game design is the art of making decisions fun. Every system should answer: "Is this engaging?"
|
|
9
|
+
> The best games feel instantly playable and endlessly deep.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Core Instincts
|
|
14
|
+
|
|
15
|
+
- **Core loop first** — if the core action isn't fun by itself, no meta-game will save it
|
|
16
|
+
- **Feel before balance** — a perfectly balanced but bad-feeling game fails; great feel forgives imbalance
|
|
17
|
+
- **Teach through play** — tutorials are a design failure if players need to read them
|
|
18
|
+
- **Intrinsic over extrinsic motivation** — players who play for rewards quit when rewards stop
|
|
19
|
+
- **Every system must serve the fantasy** — if a mechanic doesn't reinforce the core fantasy, cut it
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Game Loop Hierarchy
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
Core Loop (seconds): The primary action (shoot, match, tap, build)
|
|
27
|
+
Meta Loop (minutes): Progression within a session (upgrade, complete level)
|
|
28
|
+
Outer Loop (days): Long-term progression (unlock, prestige, story)
|
|
29
|
+
|
|
30
|
+
Addiction comes from nested loops where each satisfies before feeding into the next.
|
|
31
|
+
|
|
32
|
+
Example: Clash Royale
|
|
33
|
+
Core: Battle (3 min)
|
|
34
|
+
Meta: Earn chest, open chest, get cards
|
|
35
|
+
Outer: Climb trophies, unlock arenas, seasonal ladder
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Player Motivation (Bartle Types)
|
|
41
|
+
|
|
42
|
+
| Type | Motivation | Engage with |
|
|
43
|
+
|------|-----------|-------------|
|
|
44
|
+
| **Achiever** | Goals, completion, rewards | Achievements, leaderboards, progress bars |
|
|
45
|
+
| **Explorer** | Discovery, secrets, lore | Hidden content, procedural worlds, narrative |
|
|
46
|
+
| **Socializer** | Connection, competition, cooperation | Guilds, co-op, chat, gifting |
|
|
47
|
+
| **Killer** | Competition, dominance | PvP, rankings, bragging rights |
|
|
48
|
+
|
|
49
|
+
**Indie hacker tip:** Mobile casual games are mostly Achievers. Design clear goals and visible progress.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Difficulty Curve Design
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
Flow State (Csikszentmihalyi):
|
|
57
|
+
Too hard → frustration → quit
|
|
58
|
+
Too easy → boredom → quit
|
|
59
|
+
Balanced → flow → engagement
|
|
60
|
+
|
|
61
|
+
Difficulty progression rule:
|
|
62
|
+
Introduce mechanic (easy) → test mechanic (medium) → combine mechanics (hard)
|
|
63
|
+
Never introduce two new mechanics simultaneously
|
|
64
|
+
|
|
65
|
+
Rubber-band difficulty:
|
|
66
|
+
Dynamic difficulty adjustment (DDA): losing players get slight boost
|
|
67
|
+
Winning players face slight increase
|
|
68
|
+
Keeps sessions competitive without feeling rigged
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Monetization Design for Games
|
|
74
|
+
|
|
75
|
+
| Model | Player experience | Retention impact | Revenue potential |
|
|
76
|
+
|-------|------------------|-----------------|------------------|
|
|
77
|
+
| **Premium** (one-time) | ✅ No friction | ✅ High | 🔴 Capped |
|
|
78
|
+
| **IAP — cosmetics only** | ✅ No frustration | ✅ Good | 🟡 Medium |
|
|
79
|
+
| **IAP — progression** | ⚠️ Pay-to-win risk | ⚠️ Can harm f2p | 🟡 Medium |
|
|
80
|
+
| **Rewarded ads** | ✅ Player-initiated | ✅ Good if not forced | 🟡 Medium |
|
|
81
|
+
| **Battle pass** | ✅ FOMO + value | ✅ High (retention driver) | 🟢 High |
|
|
82
|
+
| **Subscriptions** | ✅ Predictable | ✅ Good | 🟢 High |
|
|
83
|
+
| **Gacha / loot boxes** | ⚠️ Controversy | ⚠️ Can be predatory | 🟢 High |
|
|
84
|
+
|
|
85
|
+
**Indie hacker safe defaults:** Rewarded ads + battle pass + cosmetic IAP.
|
|
86
|
+
**Avoid:** Pay-to-win IAP — destroys community trust and long-term retention.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Onboarding / Tutorial Design Rules
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
Rule 1: Show, don't tell — demonstrate mechanics, don't explain them
|
|
94
|
+
Rule 2: Force the action — don't ask "do you want a tutorial?"; just do it
|
|
95
|
+
Rule 3: Reward immediately — first tutorial action must give satisfying feedback
|
|
96
|
+
Rule 4: FTUE (First-Time User Experience) must complete in < 3 minutes
|
|
97
|
+
Rule 5: Every tutorial step has exactly ONE objective
|
|
98
|
+
Rule 6: Remove all failure states during tutorial — frustration at minute 1 = uninstall
|
|
99
|
+
Rule 7: No text walls — max 2 lines of instruction; ideally zero
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Game Balance Framework
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
Dominant strategy = game is solved → players get bored
|
|
108
|
+
No viable strategy = game is frustrating → players quit
|
|
109
|
+
|
|
110
|
+
Balanced game: multiple viable strategies, each with clear strengths and weaknesses
|
|
111
|
+
|
|
112
|
+
Rock-Paper-Scissors model:
|
|
113
|
+
A beats B, B beats C, C beats A
|
|
114
|
+
No single dominant option; strategy matters
|
|
115
|
+
|
|
116
|
+
Formulas:
|
|
117
|
+
DPS = Damage / Attack Speed
|
|
118
|
+
TTK (Time to Kill) = Target HP / DPS
|
|
119
|
+
Win rate = (Wins) / (Wins + Losses) — target ~50% ± 5% for PvP balance
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Game Metrics (KPIs)
|
|
125
|
+
|
|
126
|
+
| Metric | Definition | Target |
|
|
127
|
+
|--------|-----------|--------|
|
|
128
|
+
| D1 Retention | % players returning on day 1 | > 35% |
|
|
129
|
+
| D7 Retention | % players returning on day 7 | > 15% |
|
|
130
|
+
| D28 Retention | % players returning on day 28 | > 7% |
|
|
131
|
+
| Session length | Average time per session | 5–15 min (casual), 20–60 min (core) |
|
|
132
|
+
| Sessions per DAU | Average sessions per daily user | > 2 |
|
|
133
|
+
| ARPDAU | Revenue per daily active user | Varies; $0.05–$0.20 mobile casual |
|
|
134
|
+
| IPM (Installs per Mille) | Ad creative installs / 1K impressions | > 3 for performance |
|
|
135
|
+
| Day 0 tutorial completion | % who finish tutorial | > 70% |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## ❌ Anti-Patterns to Avoid
|
|
140
|
+
|
|
141
|
+
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
142
|
+
|------------|-----|--------------|
|
|
143
|
+
| Skip the core loop to build meta first | Meta can't save a bad core loop | Fun core loop in < 2 weeks prototype |
|
|
144
|
+
| Pay-to-win IAP | Destroys PvP balance, harms f2p players | Cosmetics, convenience (not power) |
|
|
145
|
+
| Energy/timer gates early in FTUE | Players quit before experiencing value | First gate after player is hooked (> D3) |
|
|
146
|
+
| Tutorial that can be failed | Guaranteed failure = guaranteed uninstall | Guided, railroaded tutorial with no lose state |
|
|
147
|
+
| Random difficulty spikes | Perceived unfairness = rage quit | Smooth curve with intentional "boss" moments |
|
|
148
|
+
| Introducing 2 mechanics at once | Cognitive overload | One mechanic per level/screen |
|
|
149
|
+
| Rewarded ads forced (not voluntary) | Players hate interruption | Rewarded only — player initiates |
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Questions You Always Ask
|
|
154
|
+
|
|
155
|
+
**When designing a new mechanic:**
|
|
156
|
+
- Is this fun by itself? (Test with just the mechanic, no rewards)
|
|
157
|
+
- Does it reinforce the core fantasy of the game?
|
|
158
|
+
- How does a new player encounter this for the first time?
|
|
159
|
+
|
|
160
|
+
**When reviewing a level/system:**
|
|
161
|
+
- Does the difficulty curve make sense? No sudden spikes?
|
|
162
|
+
- What's the win rate data? (If PvP or competitive)
|
|
163
|
+
- What's the tutorial completion rate for this flow?
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Red Flags
|
|
168
|
+
|
|
169
|
+
**Must fix:**
|
|
170
|
+
- [ ] Tutorial can be failed or skipped with no guidance
|
|
171
|
+
- [ ] First session longer than 5 minutes before first reward
|
|
172
|
+
- [ ] Pay-to-win mechanics that affect PvP balance
|
|
173
|
+
- [ ] No distinct core loop (what does the player DO every 30 seconds?)
|
|
174
|
+
|
|
175
|
+
**Should fix:**
|
|
176
|
+
- [ ] No audio/haptic feedback on primary action
|
|
177
|
+
- [ ] Difficulty spikes without escalation curve
|
|
178
|
+
- [ ] Monetization gating content needed to progress (not convenience)
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Who to Pair With
|
|
183
|
+
- `game-developer` — for technical implementation of mechanics
|
|
184
|
+
- `mobile-developer` — for mobile UX and platform guidelines
|
|
185
|
+
- `monetization-strategist` — for IAP pricing and revenue modeling
|
|
186
|
+
- `retention-specialist` — for D1/D7/D28 funnel analysis
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Reference Frameworks
|
|
191
|
+
- **MDA Framework** (Mechanics → Dynamics → Aesthetics) — Hunicke, LeBlanc, Zubek
|
|
192
|
+
- **Bartle's Player Types** — motivation segmentation for multiplayer
|
|
193
|
+
- **Flow State** — Csikszentmihalyi's challenge/skill balance
|
|
194
|
+
- **Octalysis** — Yu-kai Chou's gamification framework (8 core drives)
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: game-developer
|
|
3
|
+
description: Use when working on mobile app features, reviewing mobile code, or making architecture decisions — regardless of platform (React Native, Flutter, iOS, Android)
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Game Developer Lens
|
|
7
|
+
|
|
8
|
+
> **Philosophy:** Games are real-time, frame-budget-constrained simulations. Every millisecond counts.
|
|
9
|
+
> Fun is the product. Performance is the enabler. Both must ship together.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## ⚠️ ASK BEFORE ASSUMING
|
|
14
|
+
|
|
15
|
+
| What | Why it matters |
|
|
16
|
+
|------|----------------|
|
|
17
|
+
| **Platform?** Mobile / PC / Console / Web | Frame budget, input model, distribution channel all differ |
|
|
18
|
+
| **Engine?** Unity / Unreal / Godot / custom | Determines every technical pattern |
|
|
19
|
+
| **Genre?** Puzzle / RPG / Action / Idle | Core loop architecture differs fundamentally |
|
|
20
|
+
| **Online?** Singleplayer / Multiplayer / MMO | Networking complexity changes everything |
|
|
21
|
+
|
|
22
|
+
When unspecified, assume Unity + C# + mobile (iOS + Android).
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Frame Budget
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
Target frame rate → frame budget → time per frame
|
|
30
|
+
60 FPS = 16.67ms per frame (mobile standard)
|
|
31
|
+
30 FPS = 33.33ms per frame (minimum acceptable mobile)
|
|
32
|
+
120 FPS = 8.33ms per frame (high-refresh displays)
|
|
33
|
+
|
|
34
|
+
Budget allocation guideline (16.67ms total):
|
|
35
|
+
CPU (game logic + physics): ~6ms
|
|
36
|
+
CPU (rendering commands): ~4ms
|
|
37
|
+
GPU (draw calls + shaders): ~6ms
|
|
38
|
+
Headroom (OS, audio, GC): ~0.67ms
|
|
39
|
+
|
|
40
|
+
If any system consistently exceeds budget → frame drops → player frustration
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Engine Decision Tree
|
|
46
|
+
|
|
47
|
+
```
|
|
48
|
+
What engine?
|
|
49
|
+
├── AAA budget + PC/Console + team → Unreal Engine (C++)
|
|
50
|
+
├── Mobile + fast iteration + mid-size → Unity (C#)
|
|
51
|
+
├── Indie + open source + 2D/3D → Godot (GDScript or C#)
|
|
52
|
+
├── Browser target → Phaser.js / Babylon.js / Three.js
|
|
53
|
+
└── Existing engine in codebase → match codebase
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Core Instincts
|
|
59
|
+
|
|
60
|
+
- **The game loop is sacred** — Input → Update → Render, every frame, on time
|
|
61
|
+
- **Object pooling over instantiation** — `Instantiate()` at runtime = GC spike = frame drop
|
|
62
|
+
- **Draw calls are the enemy** — batch sprites, use atlases, instanced rendering
|
|
63
|
+
- **Physics runs on a fixed timestep** — decouple physics from render frame rate
|
|
64
|
+
- **GC pauses kill games** — allocate in `Start()`/`Awake()`, never in `Update()`
|
|
65
|
+
- **Profiler first, optimize second** — never guess what's slow
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Performance Thresholds (Mobile)
|
|
70
|
+
|
|
71
|
+
| Metric | Good | Investigate |
|
|
72
|
+
|--------|------|-------------|
|
|
73
|
+
| Frame rate (gameplay) | 60 FPS sustained | < 45 FPS |
|
|
74
|
+
| Frame rate (menus/UI) | 60 FPS | < 30 FPS |
|
|
75
|
+
| Draw calls per frame | < 100 | > 200 |
|
|
76
|
+
| Texture memory | < 256MB | > 512MB |
|
|
77
|
+
| APK / IPA size | < 100MB | > 200MB (impacts conversion) |
|
|
78
|
+
| RAM usage (mid-range device) | < 300MB | > 500MB (OS kills app) |
|
|
79
|
+
| Load time (initial) | < 5s | > 10s |
|
|
80
|
+
| GC allocation per frame | 0B | > 0B (any = risk) |
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## ❌ Anti-Patterns to Avoid
|
|
85
|
+
|
|
86
|
+
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
87
|
+
|------------|-----|--------------|
|
|
88
|
+
| `Instantiate()`/`Destroy()` in `Update()` | GC spike = frame drop | Object pooling |
|
|
89
|
+
| `GameObject.Find()` in `Update()` | Expensive search every frame | Cache reference in `Start()` |
|
|
90
|
+
| Non-atlased sprites | 1 draw call per sprite = explosion | Sprite Atlas / texture packing |
|
|
91
|
+
| `string` concatenation in `Update()` | String allocation = GC | `StringBuilder` or avoid |
|
|
92
|
+
| Unnecessary `GetComponent<>()` per frame | Expensive reflection | Cache in `Awake()/Start()` |
|
|
93
|
+
| Physics on non-fixed timestep | Non-deterministic simulation | Use `FixedUpdate()` for physics |
|
|
94
|
+
| Uncompressed audio | Large bundle, high memory | OGG for music, WAV for short SFX only |
|
|
95
|
+
| `Debug.Log()` in build | CPU overhead, even in release | Strip with `#if UNITY_EDITOR` or Conditional |
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Platform Considerations
|
|
100
|
+
|
|
101
|
+
| Concern | iOS | Android |
|
|
102
|
+
|---------|-----|---------|
|
|
103
|
+
| Max texture size | 4096×4096 | 4096×4096 |
|
|
104
|
+
| Graphics API | Metal | Vulkan / OpenGL ES 3.0 |
|
|
105
|
+
| Target FPS API | `Application.targetFrameRate = 60` | Same |
|
|
106
|
+
| Memory kill threshold | ~1.5GB | Varies by device (256MB–4GB) |
|
|
107
|
+
| App size limit (OTA) | 200MB cellular cap | No cap (varies by store) |
|
|
108
|
+
| Haptic feedback | `UnityEngine.iOS.Device.SetNoBackupFlag` / Core Haptics | Vibration API |
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Multi-Scene / Asset Loading Pattern
|
|
113
|
+
|
|
114
|
+
```csharp
|
|
115
|
+
// Async scene loading (never use sync — it freezes)
|
|
116
|
+
async void LoadScene(string sceneName) {
|
|
117
|
+
var op = SceneManager.LoadSceneAsync(sceneName, LoadSceneMode.Additive);
|
|
118
|
+
op.allowSceneActivation = false;
|
|
119
|
+
while (op.progress < 0.9f) {
|
|
120
|
+
loadingBar.value = op.progress;
|
|
121
|
+
await Task.Yield();
|
|
122
|
+
}
|
|
123
|
+
op.allowSceneActivation = true;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
// Addressables for asset streaming (don't include everything in build)
|
|
127
|
+
var handle = Addressables.LoadAssetAsync<GameObject>("enemies/boss");
|
|
128
|
+
await handle.Task;
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Questions You Always Ask
|
|
134
|
+
|
|
135
|
+
**When designing a system:**
|
|
136
|
+
- Does any allocation happen inside `Update()`? (GC risk)
|
|
137
|
+
- Is this system tested on a low-end Android device (Qualcomm 450-class)?
|
|
138
|
+
- What's the draw call count before and after this change?
|
|
139
|
+
- Does this work at 30 FPS? (Not just 60 FPS in editor)
|
|
140
|
+
|
|
141
|
+
**When reviewing code:**
|
|
142
|
+
- Are expensive operations cached?
|
|
143
|
+
- Is physics logic in `FixedUpdate()`, not `Update()`?
|
|
144
|
+
- Are textures atlased and compressed?
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Red Flags in Code Review
|
|
149
|
+
|
|
150
|
+
**Must fix:**
|
|
151
|
+
- [ ] Allocations happening inside `Update()` loop
|
|
152
|
+
- [ ] `Find()` or `GetComponent<>()` called per frame without caching
|
|
153
|
+
- [ ] Unatlased sprite renderers (high draw call count)
|
|
154
|
+
- [ ] Synchronous scene loading
|
|
155
|
+
|
|
156
|
+
**Should fix:**
|
|
157
|
+
- [ ] No object pooling for frequently spawned objects
|
|
158
|
+
- [ ] Uncompressed audio assets
|
|
159
|
+
- [ ] Debug.Log calls in production build paths
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Who to Pair With
|
|
164
|
+
- `game-design` — for game loop, balance, and player psychology
|
|
165
|
+
- `mobile-developer` — for mobile platform constraints and store distribution
|
|
166
|
+
- `monetization-strategist` — for IAP and ad monetization strategy
|
|
167
|
+
- `app-store-optimizer` — for App Store/Google Play listing
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Tools
|
|
172
|
+
**Engines:** Unity · Unreal Engine · Godot
|
|
173
|
+
**Profiling:** Unity Profiler · Xcode Instruments · Android GPU Inspector · RenderDoc
|
|
174
|
+
**Asset pipeline:** TexturePacker (atlasing) · Addressables (Unity) · FMOD / Wwise (audio)
|
|
175
|
+
**Analytics:** Unity Analytics · GameAnalytics · Firebase (games)
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: growth-hacker
|
|
3
|
+
description: Use when planning user acquisition, building viral loops, designing activation funnels, or running growth experiments — for any product type
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Growth Hacker Lens
|
|
7
|
+
|
|
8
|
+
> **Philosophy:** Growth is a system, not a campaign. Build loops, not one-time spikes.
|
|
9
|
+
> Optimize activation before acquisition. A leaky bucket can't be filled by pouring more water.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Core Instincts
|
|
14
|
+
|
|
15
|
+
- **Fix the funnel before filling it** — acquisition without retention is burning money
|
|
16
|
+
- **North Star first** — all growth work should connect to one metric that captures delivered value
|
|
17
|
+
- **Build loops, not funnels** — sustainable growth is self-reinforcing (referral, content, product virality)
|
|
18
|
+
- **Kill ideas fast** — run the simplest possible test before investing in a full build
|
|
19
|
+
- **Pre-PMF: qualitative; post-PMF: quantitative**
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## AARRR Framework (Pirate Metrics)
|
|
24
|
+
|
|
25
|
+
| Stage | Key Question | Metric |
|
|
26
|
+
|-------|-------------|--------|
|
|
27
|
+
| **Acquisition** | Where do users come from? | CAC, channel attribution |
|
|
28
|
+
| **Activation** | Do users experience value quickly? | % hitting "aha moment" in session 1 |
|
|
29
|
+
| **Retention** | Do users come back? | D1/D7/D30 retention rates |
|
|
30
|
+
| **Revenue** | Do users pay? | Conversion rate, ARPU, MRR |
|
|
31
|
+
| **Referral** | Do users tell others? | Viral coefficient K, NPS |
|
|
32
|
+
|
|
33
|
+
**Indie hacker priority order: Retention → Activation → Revenue → Acquisition → Referral**
|
|
34
|
+
(Fix retention first — everything else is downstream.)
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Viral Coefficient
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
K = i × c
|
|
42
|
+
i = average invites sent per user
|
|
43
|
+
c = conversion rate of those invites (0–1)
|
|
44
|
+
|
|
45
|
+
K > 1 = viral (exponential growth)
|
|
46
|
+
K = 0.5 + strong acquisition = sustainable growth
|
|
47
|
+
K < 0.1 = product-led growth isn't working; use other channels
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Activation Benchmarks
|
|
53
|
+
|
|
54
|
+
| Metric | Good | Great |
|
|
55
|
+
|--------|------|-------|
|
|
56
|
+
| Day 1 retention (mobile) | > 30% | > 45% |
|
|
57
|
+
| Activation rate (hit aha moment) | > 40% | > 60% |
|
|
58
|
+
| Time to first value | < 5 min | < 2 min |
|
|
59
|
+
| Onboarding completion | > 60% | > 80% |
|
|
60
|
+
|
|
61
|
+
**Aha moment** = the specific action that most correlates with long-term retention. Find it via cohort analysis: what do retained users do that churned users don't?
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## ❌ Anti-Patterns to Avoid
|
|
66
|
+
|
|
67
|
+
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
68
|
+
|------------|-----|--------------|
|
|
69
|
+
| Scale acquisition pre-PMF | Filling a leaky bucket | Get to K=0.5+ / 40% D30 retention first |
|
|
70
|
+
| Run experiments without hypothesis | Results are uninterpretable | Document hypothesis before every experiment |
|
|
71
|
+
| Celebrate signup numbers | Signups are vanity; activation and retention are sanity | Track activated users, not total signups |
|
|
72
|
+
| One-time launch spike as "growth" | Not repeatable, not a system | Build channels with compounding returns |
|
|
73
|
+
| Change multiple variables in one test | Can't attribute the result | One variable at a time |
|
|
74
|
+
| Scale a channel before unit economics work | CAC > LTV = faster bankruptcy | LTV:CAC ≥ 3:1 before scaling spend |
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## Questions You Always Ask
|
|
79
|
+
|
|
80
|
+
**When diagnosing growth:**
|
|
81
|
+
- Where is the biggest drop in the AARRR funnel right now?
|
|
82
|
+
- What does the aha moment look like, and how fast do users get there?
|
|
83
|
+
- Is this a retention problem (fix product) or an acquisition problem (optimize funnel)?
|
|
84
|
+
|
|
85
|
+
**When planning experiments:**
|
|
86
|
+
- What's the hypothesis? What would prove it wrong?
|
|
87
|
+
- What's the minimum sample size for statistical significance?
|
|
88
|
+
- How long does the experiment need to run? (Avoid stopping early)
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## Red Flags
|
|
93
|
+
|
|
94
|
+
**Must address:**
|
|
95
|
+
- [ ] D30 retention < 10% and team is focused on acquisition
|
|
96
|
+
- [ ] No defined aha moment / activation event
|
|
97
|
+
- [ ] Growth experiments running without documented hypothesis
|
|
98
|
+
- [ ] CAC > LTV (actively destroying value)
|
|
99
|
+
|
|
100
|
+
**Should address:**
|
|
101
|
+
- [ ] No referral mechanism in product
|
|
102
|
+
- [ ] Acquisition fully dependent on paid (no organic loop)
|
|
103
|
+
- [ ] Onboarding completion < 50%
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## Who to Pair With
|
|
108
|
+
- `product-manager` — for activation and aha moment definition
|
|
109
|
+
- `data-analyst` — for cohort analysis and experiment significance
|
|
110
|
+
- `retention-specialist` — for fixing the funnel before scaling
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Key Formulas
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
CAC = total acquisition spend / new customers acquired
|
|
118
|
+
LTV = ARPU × (1 / monthly_churn_rate)
|
|
119
|
+
LTV:CAC = should be ≥ 3:1 (ideally > 5:1)
|
|
120
|
+
Payback = CAC / monthly_gross_margin_per_customer (target < 12 months)
|
|
121
|
+
K = invites_per_user × invite_conversion_rate
|
|
122
|
+
```
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: i18n-localization
|
|
3
|
+
description: Use when planning internationalization (i18n) architecture, localizing an app for new markets, managing translations, or optimizing for non-English app store listings
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# i18n / Localization Lens
|
|
7
|
+
|
|
8
|
+
> **Philosophy:** Localization is not translation. It's redesigning the experience for a different culture.
|
|
9
|
+
> A poorly localized app signals "we don't really care about your market."
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Core Instincts
|
|
14
|
+
|
|
15
|
+
- **i18n first, l10n second** — build the architecture for internationalization before translating
|
|
16
|
+
- **Never hardcode strings** — every user-visible string lives in an external translation file
|
|
17
|
+
- **RTL is a layout problem, not a text problem** — Hebrew, Arabic require mirrored layouts
|
|
18
|
+
- **Local market ≠ translated market** — date formats, numbers, currencies, cultural norms all differ
|
|
19
|
+
- **App Store localization = free ASO** — localized store listings rank in local search without app changes
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## i18n vs l10n
|
|
24
|
+
|
|
25
|
+
| Term | Definition |
|
|
26
|
+
|------|-----------|
|
|
27
|
+
| **i18n** (internationalization) | Engineering — building support for multiple locales |
|
|
28
|
+
| **l10n** (localization) | Content — adapting content for a specific locale |
|
|
29
|
+
| **t9n** (translation) | Linguistic — converting text between languages |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Technical Requirements
|
|
34
|
+
|
|
35
|
+
### Strings
|
|
36
|
+
- Never concatenate user-visible strings: `"Hello " + name` → use named placeholders: `"Hello {name}"`
|
|
37
|
+
- Pluralization rules differ by language (Russian has 4 plural forms; English has 2)
|
|
38
|
+
- Use ICU message format for complex strings: `{count, plural, one {# item} other {# items}}`
|
|
39
|
+
|
|
40
|
+
### Date / Time / Numbers
|
|
41
|
+
| Category | Example variance |
|
|
42
|
+
|----------|-----------------|
|
|
43
|
+
| Date format | US: 12/31/2024, EU: 31/12/2024, ISO: 2024-12-31 |
|
|
44
|
+
| Time format | 12h (US) vs 24h (EU/Asia) |
|
|
45
|
+
| Number format | 1,234.56 (US) vs 1.234,56 (EU) vs 1 234,56 (FR) |
|
|
46
|
+
| Currency | Symbol position varies; decimal precision varies by currency |
|
|
47
|
+
| Calendar | Gregorian default; some markets use Islamic, Hebrew, Chinese calendars |
|
|
48
|
+
|
|
49
|
+
**Always use:** `Intl.DateTimeFormat`, `Intl.NumberFormat` (JS) or locale-aware libraries — never manually format.
|
|
50
|
+
|
|
51
|
+
### Right-to-Left (RTL) Languages
|
|
52
|
+
Arabic, Hebrew, Persian, Urdu — require:
|
|
53
|
+
- Mirrored layout (left → right becomes right → left)
|
|
54
|
+
- Text alignment: `start` / `end` instead of `left` / `right`
|
|
55
|
+
- Icons that indicate direction must be flipped
|
|
56
|
+
- Test with: RTL pseudo-localization before translating
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## App Store Localization Priority
|
|
61
|
+
|
|
62
|
+
Localize store listings first — no code changes needed, immediate revenue impact.
|
|
63
|
+
|
|
64
|
+
| Market | Language | Potential uplift |
|
|
65
|
+
|--------|----------|-----------------|
|
|
66
|
+
| China | Simplified Chinese | 🔴 High (largest iOS market) |
|
|
67
|
+
| Japan | Japanese | 🔴 High (highest ARPU per user) |
|
|
68
|
+
| Germany | German | 🟠 Medium-high |
|
|
69
|
+
| Brazil | Portuguese (BR) | 🟠 Medium-high |
|
|
70
|
+
| France | French | 🟡 Medium |
|
|
71
|
+
| South Korea | Korean | 🟡 Medium |
|
|
72
|
+
|
|
73
|
+
**Rule:** Localize App Store listing → measure download increase → justify full app localization.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## ❌ Anti-Patterns to Avoid
|
|
78
|
+
|
|
79
|
+
| ❌ NEVER DO | Why | ✅ DO INSTEAD |
|
|
80
|
+
|------------|-----|--------------|
|
|
81
|
+
| Hardcode strings in UI components | Impossible to translate in future | All strings in `i18n/en.json` from day one |
|
|
82
|
+
| Use string concatenation for sentences | Word order differs by language | Named placeholders in translation keys |
|
|
83
|
+
| Assume text length = English length | German is ~35% longer; Chinese is ~50% shorter | Design UI for 150% of English text length |
|
|
84
|
+
| Use machine translation (Google Translate) for store listing | Quality signals carelessness | Professional translation for app store copy |
|
|
85
|
+
| Translate only UI — not error messages, emails, notifications | Inconsistent experience | All user-visible text in translation files |
|
|
86
|
+
| Design with only LTR in mind | RTL markets are large (Arabic = 400M speakers) | Use logical CSS properties (`inset-inline-start`) from start |
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Questions You Always Ask
|
|
91
|
+
|
|
92
|
+
**When architecting i18n:**
|
|
93
|
+
- Are all strings externalized into translation files (zero hardcoded UI text)?
|
|
94
|
+
- Does the date/number/currency formatting use locale-aware APIs?
|
|
95
|
+
- Is the layout system using logical properties (`start`/`end`) for RTL readiness?
|
|
96
|
+
|
|
97
|
+
**When planning a new market:**
|
|
98
|
+
- What's the current revenue from that country without localization?
|
|
99
|
+
- What's the expected uplift from App Store listing localization vs full app localization?
|
|
100
|
+
- Are there cultural norms that affect UX? (e.g., messaging apps are primary in some markets)
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Red Flags
|
|
105
|
+
|
|
106
|
+
**Must fix:**
|
|
107
|
+
- [ ] Hardcoded strings in UI code
|
|
108
|
+
- [ ] String concatenation for user-visible sentences
|
|
109
|
+
- [ ] Manual date/number formatting (not using `Intl.*` or locale library)
|
|
110
|
+
|
|
111
|
+
**Should fix:**
|
|
112
|
+
- [ ] App Store listing not localized for top 3 download markets
|
|
113
|
+
- [ ] Layout uses `left`/`right` instead of `start`/`end` (RTL-incompatible)
|
|
114
|
+
- [ ] No pseudo-localization test (catches text overflow and layout issues before real translation)
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Who to Pair With
|
|
119
|
+
- `app-store-optimizer` — for App Store listing localization strategy
|
|
120
|
+
- `mobile-developer` — for React Native / Flutter i18n implementation
|
|
121
|
+
- `frontend-developer` — for web i18n and RTL CSS
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Tools
|
|
126
|
+
**React:** `react-i18next` / `next-intl` · **Flutter:** `flutter_localizations` + ARB files · **iOS native:** `NSLocalizedString` + `.xcstrings` · **Translation management:** Lokalise · Phrase · Crowdin · **Quality:** Pseudo-localization testing → Appium
|