agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/psychology/skills/agileflow-retention/references/retention-patterns.md

@@ -0,0 +1,279 @@
+# Retention Patterns Reference
+
+**Load this when:** implementing a specific retention mechanic, evaluating whether a mechanic is evidence-based, designing a notification strategy, or auditing which mechanics the product already has.
+
+Each pattern includes: psychological basis, key research, real-world evidence, and implementation steps.
+
+---
+
+## 1. Streaks
+
+### What it is
+
+A counter showing consecutive days (or sessions) a user has performed a target behavior. Accompanied by a visual indicator (fire icon, chain) and often a recovery mechanic (streak freeze).
+
+### Psychological basis
+
+**Loss aversion** (Kahneman & Tversky, 1979): humans weight potential losses approximately twice as heavily as equivalent gains. A user with a 45-day streak has accumulated something they are strongly motivated not to lose.
+
+**Research:** Kahneman, D. & Tversky, A. (1979). "Prospect Theory: An Analysis of Decision under Risk." _Econometrica_, 47(2), 263–292.
+
+### Evidence
+
+- **Duolingo internal data:** Users with a 30-day streak are retained at approximately 2.4× the rate of users without streaks. This is one of the highest ROI features in Duolingo's product.
+- **Duolingo streak freeze:** Allowing users to "repair" missed days with a streak freeze (earned or purchased) dramatically reduces streak abandonment. Without it, a single missed day causes permanent churn for a significant segment of streak users.
+- **GitHub contribution graph:** GitHub's "green squares" contribution history functions as a streak visual, driving daily commit behavior among developers.
+
+### Implementation steps
+
+1. Define the target behavior (the action that increments the streak)
+2. Set the streak increment unit (daily is most common; weekly for lower-frequency behaviors)
+3. Build the streak counter with a visually satisfying increment animation
+4. Add a prominent visual indicator that degrades visually as the streak approaches 24-hour expiry
+5. Implement streak freeze / recovery mechanic — allow at most 1–2 misses before streak resets
+6. Add a "streak at risk" notification that fires 2–4 hours before the deadline (high-converting)
+7. Celebrate milestone streaks (7 days, 30 days, 100 days) with special animations/rewards
+8. Track: average streak length, streak abandonment rate, 7-day retention by streak cohort
+
+### Failure modes
+
+- Streak anxiety: users who find the pressure aversive will churn entirely to escape. Offer an opt-out.
+- Fake engagement: users complete the minimum to preserve the streak without real value. Audit whether streak behavior correlates with core value delivery.
+
+---
+
+## 2. Progress Bars and Completion Indicators
+
+### What it is
+
+A visual indicator of how complete a user's profile, onboarding, or task sequence is. Shows a percentage or step count and highlights the next actionable step.
+
+### Psychological basis
+
+**Commitment and consistency** (Cialdini, 1984): once a person has started something, they are psychologically motivated to complete it. A visible progress bar activates this commitment.
+
+**Zeigarnik Effect** (1927): incomplete tasks are held in working memory more vividly than completed tasks. A progress bar at 60% creates a persistent cognitive "open loop" that drives users back.
+
+**Research:**
+
+- Cialdini, R.B. (1984). _Influence: The Psychology of Persuasion._ William Morrow.
+- Zeigarnik, B. (1927). "Das Behalten erledigter und unerledigter Handlungen." _Psychologische Forschung_, 9, 1–85.
+
+### Evidence
+
+- **LinkedIn profile completeness bar:** LinkedIn's profile completeness indicator, showing steps like "Add a photo", "Add your current position", significantly increased profile completion rates. Completed profiles generated more connection requests, improving network effects and retention.
+- **Progress-based onboarding** consistently outperforms step-by-step linear flows in A/B tests across multiple SaaS products. Users who see how far they've come are more likely to continue than users in a pure sequence.
+
+### Implementation steps
+
+1. Define what "100% complete" means (profile, onboarding, feature adoption)
+2. Weight steps by impact on retention, not just effort
+3. Show the progress bar prominently in the UI with exact percentage
+4. For each step below 100%, highlight the single most impactful next action
+5. Never show a progress bar at 0% — consider pre-filling with "free" initial progress (see Endowed Progress below)
+6. Celebrate completion with a clear reward (access to a feature, a visual transformation)
+7. Remove the bar once complete — don't turn a completion into a persistent reminder of a finished task
+
+### Failure modes
+
+- Progress bar for its own sake: if completion doesn't unlock real value, users learn to ignore it
+- Too many steps: a progress bar with 15 items feels overwhelming. Cap at 5–7 major items.
+
+---
+
+## 3. Variable Reward Schedules
+
+### What it is
+
+Reward delivery that is unpredictable — sometimes you get a big reward, sometimes a small one, sometimes nothing. The unpredictability is the feature, not a bug.
+
+### Psychological basis
+
+**Operant conditioning / variable ratio reinforcement** (Skinner, 1938): a variable ratio schedule — where a reward occurs after an unpredictable number of responses — produces the highest response rate and the greatest resistance to extinction of all reward schedules.
+
+**Research:** Skinner, B.F. (1938). _The Behavior of Organisms: An Experimental Analysis._ Appleton-Century-Crofts.
+
+The mechanism: dopamine is released in anticipation of a potential reward, not just upon receiving it. Unpredictability maximizes anticipatory dopamine release, which drives continued behavior.
+
+### Evidence
+
+- **Slot machines:** The canonical application of variable ratio schedules — the most addictive gambling mechanic ever designed.
+- **Instagram likes:** The delay between posting and seeing likes creates variability. The "pull to refresh" gesture that reveals new likes is a discrete slot machine pull.
+- **Email inbox:** The expectation of an interesting email drives inbox refreshing behavior, even when most emails are irrelevant.
+- **Wordle:** The daily single puzzle with uncertain success creates anticipation. Players don't know if today's word will be easy or hard.
+- **Loot boxes in games:** Proven retention mechanic; now regulated in several countries due to gambling parallels.
+
+### Implementation steps
+
+1. Identify the reward in your product (social validation, useful information, achievement, discovery)
+2. Remove predictability: don't deliver the reward on a fixed schedule
+3. Add signal uncertainty: "You have X new notifications" without showing them immediately
+4. Design pull-to-reveal moments: the act of checking creates anticipation
+5. Use occasional "jackpot" moments: unexpected large rewards (Spotify Discover Weekly, unexpected free premium feature)
+6. Do NOT make every interaction rewarding — some variability (occasionally nothing interesting) is essential
+
+### Ethical note
+
+Variable reward schedules are the most powerful and most ethically fraught mechanic. Apply only to behaviors that deliver genuine value to users. "Checking for notifications to see if friends engaged with my content" is legitimate. "Checking for algorithmically outraged content to maximize session time" crosses into manipulation.
+
+---
+
+## 4. Social Proof
+
+### What it is
+
+Displaying evidence that other people are using, enjoying, or valuing the product — reducing uncertainty and creating behavioral norms.
+
+### Psychological basis
+
+**Social proof** (Cialdini, 1984): when uncertain about the correct course of action, people look to what others are doing to determine the right behavior. The more similar those others are perceived to be, the stronger the effect.
+
+**Research:** Cialdini, R.B. (1984). _Influence: The Psychology of Persuasion._ William Morrow.
+
+### Evidence
+
+- **Airbnb "Usually books within 24 hours":** Showing host responsiveness as social proof increased booking conversion rates measurably (Airbnb A/B test data).
+- **Amazon reviews:** Product review counts are one of the strongest conversion predictors. Zero reviews dramatically suppress conversion even with positive ratings.
+- **"X people are viewing this item right now":** Urgency-amplified social proof shown on hotel booking sites. When genuine, increases conversion; when fabricated, creates distrust when discovered.
+- **Twitter follower counts:** Public follower counts are social proof of account credibility. Accounts with 0 followers receive lower engagement than accounts with 1,000 followers, even for identical content.
+
+### Implementation steps
+
+1. Identify the uncertainty your user faces (Is this product worth my time? Will others judge me? Is this the right choice?)
+2. Select the most credible social proof type for that uncertainty:
+   - **Aggregate numbers:** "10,000 teams use this"
+   - **Activity signals:** "Viewed 47 times today"
+   - **Testimonials:** Specific, named, with context
+   - **Similar user proof:** "Teams like yours" — similarity amplifies the effect
+3. Display proof at the decision moment, not on a separate testimonials page
+4. Keep proof honest — fabricated social proof causes permanent trust damage when discovered
+5. Update counts in real-time or near-real-time; stale numbers undermine credibility
+
+---
+
+## 5. Personalized Onboarding and the Aha Moment
+
+### What it is
+
+The "aha moment" is the specific user action that correlates most strongly with long-term retention. Personalized onboarding redesigns the first-session experience to reach that moment as quickly as possible.
+
+### Psychological basis
+
+**Value realization:** Retention is a function of how quickly users experience the core value of the product. Users who reach value in session 1 have dramatically higher D7 and D30 retention.
+
+**Personalization effect:** Users who are asked about their goals and receive a tailored experience feel the product is made for them (Fogg's belonging motivator + SDT autonomy need).
+
+### Evidence
+
+- **Facebook "7 friends in 10 days":** Facebook's growth team discovered that users who connected with at least 7 friends in their first 10 days had dramatically higher long-term retention. This became the north star for onboarding optimization. _Source: Chamath Palihapitiya, former VP of Growth at Facebook, multiple talks._
+- **Twitter "follow 30 accounts in first session":** Twitter's retention team found this threshold strongly predicted whether a new user would become an active user. The onboarding flow was redesigned to guide users to this milestone. _Source: Josh Elman, former Twitter Product, multiple talks._
+- **Slack "2,000 messages exchanged":** Teams that had sent at least 2,000 messages had a 93% retention rate after 90 days. Below that threshold, retention was significantly lower. _Source: Slack growth team data, cited in multiple product publications._
+- **Dropbox "first upload":** Users who uploaded at least one file in their first session had dramatically higher 30-day retention. Dropbox redesigned its install flow around reaching this milestone faster.
+
+### Implementation steps
+
+1. Analyze your retention data: which action in week 1 most strongly predicts D30 retention? That is your aha moment.
+2. If you don't have data, run a survey with retained users: "What was the moment you knew you'd keep using this?"
+3. Redesign onboarding as a guided path to that single moment — cut everything that doesn't contribute to reaching it
+4. Add personalization questions that let you tailor the path ("What's your main goal?")
+5. Measure "time to aha moment" as a core onboarding metric, and track it by cohort
+6. For each new user segment, identify whether the aha moment is the same or different
+
+---
+
+## 6. Behavioral Notifications
+
+### What it is
+
+Push notifications or emails triggered by specific user behaviors or contextual signals, rather than sent on a marketing schedule.
+
+### Psychological basis
+
+**Relevance and timing** (Fogg's Prompt principle): a prompt that arrives at the right motivation state is far more effective than a generic prompt. Behavioral triggers fire when the user is most ready to act.
+
+### Evidence
+
+- **Urban Airship (now Airship) data (2016):** Push notifications triggered by user behavior or location generated 2–5× higher engagement rates than broadcast marketing messages. _Source: Urban Airship Push Notification Benchmark Report, 2016._
+- **Optimal frequency:** 2–5 notifications per week is the optimal range for most apps before opt-out rates spike. _Source: Localytics Push Notification Benchmark, 2017._
+- **Personalization lift:** Personalized push notifications (including first name, relevant content) show 4× higher click rates than generic notifications. _Source: Leanplum, 2017._
+
+### Notification types by effectiveness (high to low)
+
+1. **Triggered by user action:** "Someone replied to your comment" — highest relevance, user-initiated context
+2. **Triggered by milestone:** "You're on a 7-day streak!" — relevant to user's own progress
+3. **Triggered by friend action:** "Alice mentioned you" — social relevance
+4. **Triggered by inactivity:** "We miss you — here's what you missed" — re-engagement
+5. **Triggered by marketing calendar:** "Check out our summer sale" — lowest relevance, highest opt-out
+
+### Implementation steps
+
+1. Build behavioral triggers first — instrument user actions that warrant notification
+2. Create a notification preference system — let users control frequency and type
+3. Implement "quiet hours" — never send at 2am
+4. A/B test notification copy: personal, specific, and action-oriented outperforms generic
+5. Track per-notification opt-out rates — a notification type with >10% opt-out rate is harming retention
+6. Respect unsubscribes immediately and completely
+
+---
+
+## 7. Endowed Progress Effect
+
+### What it is
+
+Giving users artificially "head start" progress before they have earned it — pre-filling a progress bar, awarding bonus points at signup, starting a loyalty card with 2 stamps already punched.
+
+### Psychological basis
+
+**Goal gradient hypothesis** (Hull, 1932): motivation to complete a goal increases as you get closer to it. The endowed progress effect accelerates this by moving users artificially closer to the goal from the start.
+
+**Key research:** Nunes, J.C. & Drèze, X. (2006). "The Endowed Progress Effect: How Artificial Advancement Increases Effort." _Journal of Consumer Research_, 32(4), 504–512.
+
+### Evidence
+
+- **Nunes & Drèze (2006) car wash loyalty card study:** Customers given a loyalty card pre-stamped with 2 free stamps (requiring 10 total, so 8 more needed) completed the card at a significantly higher rate than customers given a card requiring 8 stamps with no head start — even though the effort required was identical. The "free" progress framing was enough to increase completion.
+- **LinkedIn "Profile Strength" meter:** Starting new users with a "Beginner" rating (rather than empty/0) leverages endowed progress. Users feel they have something to build on rather than starting from nothing.
+- **Welcome bonuses in apps:** Giving new users bonus currency, initial XP, or pre-loaded settings creates investment and leverages endowed progress.
+
+### Implementation steps
+
+1. Identify a progress mechanic in your product (profile completion, level, points, skills)
+2. Give new users free initial progress that represents 10–20% of the goal
+3. Frame it as a head start: "You're already at level 2" or "2 out of 10 steps complete"
+4. Ensure the head start is real (don't show 10% on a progress bar that requires 100 real steps, then show nothing happening for a long time)
+5. The effect is strongest for goals where users can see the distance remaining
+
+---
+
+## 8. Loss Aversion Mechanics
+
+### What it is
+
+Mechanics that frame inaction as losing something the user already has, rather than framing action as gaining something new.
+
+### Psychological basis
+
+**Prospect Theory** (Kahneman & Tversky, 1979): in value function terms, losses are felt approximately 2× more intensely than equivalent gains. "You'll lose your streak" is psychologically twice as motivating as "You'll gain streak points."
+
+**Research:** Kahneman, D. & Tversky, A. (1979). "Prospect Theory: An Analysis of Decision under Risk." _Econometrica_, 47(2), 263–292. _Nobel Prize in Economics, 2002._
+
+### Evidence
+
+- **Duolingo streak saver notification:** "You're about to lose your 45-day streak — complete a lesson now" is reported by Duolingo as one of their highest-converting notification messages. The loss framing dramatically outperforms "Maintain your streak" (gain framing).
+- **LinkedIn "Your profile appeared in 8 searches this week":** Framing search visibility as something you have (and could have more of with a better profile) leverages loss aversion around missing out on opportunities.
+- **Free trial → cancellation:** The period of free premium use creates the sensation of having premium features. The cancellation notification ("You will lose access to X, Y, Z in 3 days") leverages loss aversion. This is why free-to-paid conversion rates peak at trial end, not trial start.
+- **"You have unread messages":** The badge on email/messaging apps frames not checking as accumulating something you'll lose track of — leveraging loss aversion around missed communication.
+
+### Implementation steps
+
+1. Identify what the user has accumulated (streaks, premium access, unread items, profile strength, saved content)
+2. Frame retention-critical notifications as loss prevention, not gain opportunity
+3. Use specific numbers: "You're about to lose your 23-day streak" outperforms "Keep your streak going"
+4. Time notifications to fire before the loss moment, not after it (too late)
+5. Offer a recovery mechanic: users who lose something are more likely to churn entirely; a recovery path keeps them engaged
+
+### Ethical boundary
+
+Loss aversion is the most manipulable mechanic on this list. The line between motivation and anxiety-inducing dark pattern is real.
+
+- **Legitimate:** Loss framing for something the user genuinely values (their streak they built, their trial access to features they use)
+- **Manipulation:** Fabricating loss ("Your account is about to be deleted" for minor inactivity), creating artificial stakes, manufactured urgency with no real consequence

package/content/plugins/psychology/skills/agileflow-retention/workflows/design-retention-feature.md

@@ -0,0 +1,287 @@
+# Workflow: Design a Retention Feature
+
+**Follow this when:** the user wants to design a new retention mechanic — a streak system, notification strategy, progress indicator, social feature, reward loop, or any other habit-forming feature.
+
+**Time estimate:** 30–60 minutes for a complete feature design with psychological rationale.
+
+**Output:** A fully specified retention mechanic with trigger, action, reward, investment, ethical check, and measurement plan.
+
+---
+
+## Before you start
+
+Ask the user:
+
+1. Which mechanic type are they considering? (streak, progress bar, notifications, social proof, variable reward, something else)
+2. What user behavior do they want to become habitual? (be specific: "open the app daily", "complete a project update each Friday", "share work with a colleague weekly")
+3. What is the target user segment? (new users / lapsed users / power users)
+4. What does success look like? (D7 retention improvement, DAU/MAU increase, session frequency increase)
+
+If the user doesn't know which mechanic to use, help them choose one using the model selection table in `references/psychology-models.md`.
+
+---
+
+## Step 1: Choose the psychological model
+
+**Goal:** Match the mechanic to the right model before designing any feature.
+
+| Retention goal                      | Best model                                   | Best mechanic                                          |
+| ----------------------------------- | -------------------------------------------- | ------------------------------------------------------ |
+| Build a new daily habit             | Hook Model + Habit Loop                      | Streak + daily content + notifications                 |
+| Increase onboarding completion      | Fogg B=MAP                                   | Progress bar + endowed progress + facilitator prompts  |
+| Drive social engagement             | Hook Model (Tribe rewards) + SDT Relatedness | Social features + variable social validation           |
+| Reduce churn among engaged users    | Loss aversion + Investment                   | Streak mechanics + investment layer                    |
+| Increase feature adoption           | Fogg B=MAP (ability) + Endowed Progress      | Guided flow + pre-filled defaults + progress indicator |
+| Build intrinsic long-term retention | SDT                                          | Autonomy + competence progression + community          |
+
+Select the primary model and note why it fits this specific challenge.
+
+---
+
+## Step 2: Define the target behavior
+
+**Goal:** Be precise about what behavior you want users to perform and how often.
+
+Fill in this template:
+
+```
+Target behavior: [Specific, observable action]
+Frequency: [Daily / Weekly / Per session / On trigger]
+Target user state: [What emotion or context should trigger this?]
+Minimum viable version: [The simplest version of the behavior]
+```
+
+Examples:
+
+- "Complete one lesson in the app. Daily. When the user has free time or is waiting. Minimum: answer 3 questions."
+- "Update project status. Weekly on Friday afternoon. When wrapping up the work week. Minimum: one sentence."
+- "Log a workout. After exercising. When arriving home from exercise. Minimum: tap 'I worked out today'."
+
+The minimum viable behavior matters for Fogg's ability lever. The smaller the minimum behavior, the lower the motivation threshold required to perform it.
+
+---
+
+## Step 3: Design the trigger
+
+**Goal:** Design an external trigger that will eventually be replaced by an internal trigger.
+
+**External trigger design:**
+
+1. Identify the trigger delivery channel:
+   - Push notification (requires permission; most immediate)
+   - Email (no permission required; lower urgency)
+   - In-app badge or indicator (only reaches users already in app)
+   - SMS (highest open rates; highest friction to opt into)
+
+2. Design the trigger timing:
+   - Behavioral: triggered by user action or inaction ("user hasn't logged in for 3 days")
+   - Time-based: tied to a specific time the user has indicated they prefer
+   - Calendar-based: tied to a recurring event (end of work week, before a deadline)
+   - Location-based: triggered by physical context if available
+
+3. Write the trigger copy using these principles:
+   - Personal: use name or specific context ("Your 14-day streak is at risk")
+   - Loss framing: "You're about to lose X" outperforms "Keep your X going"
+   - Specific numbers: "You're on day 14" not "You have a streak"
+   - Single action: tell them exactly what to do ("Tap here to complete today's lesson")
+
+4. Design for internal trigger formation:
+   - Which emotion should become associated with opening the product?
+   - How does the product reliably resolve that emotion?
+   - Document this: "We want users to associate [boredom / procrastination avoidance / productivity] with opening [product]"
+   - Check after 4–6 weeks of external triggers: are users opening without the notification?
+
+**Trigger quality checklist:**
+
+- [ ] Behavioral trigger, not scheduled blast
+- [ ] Fires at the right motivation moment (not at 2am, not during user's known low-engagement hours)
+- [ ] Loss-framed copy with specific numbers
+- [ ] Single clear action
+- [ ] Opt-out available and respected
+
+---
+
+## Step 4: Reduce friction in the action
+
+**Goal:** Make the target behavior as easy as possible to perform in response to the trigger.
+
+Apply Fogg's 6 simplicity factors to the path from trigger to completed behavior:
+
+| Factor          | Current state         | Target state               | Change required                     |
+| --------------- | --------------------- | -------------------------- | ----------------------------------- |
+| Time            | [how long?]           | < 2 minutes                | [what to remove]                    |
+| Money           | [any cost?]           | Free to perform            | [if cost exists, justify or remove] |
+| Physical effort | [taps/clicks]         | < 3 taps from notification | [what to streamline]                |
+| Brain cycles    | [decisions required?] | 0 decisions, 1 action      | [what to default or remove]         |
+| Social deviance | [does it feel weird?] | Normal, expected           | [normalize or destigmatize]         |
+| Non-routine     | [familiar or new?]    | Familiar pattern           | [use existing UI patterns]          |
+
+**The one-tap principle:** Wherever possible, the notification should take users directly to the action — not to a home screen they have to navigate from. Deep link from notification to the specific action.
+
+---
+
+## Step 5: Design the reward
+
+**Goal:** Deliver a variable, autonomy-preserving reward immediately after the target behavior.
+
+**Choose the reward type:**
+
+| Type                   | What it delivers                           | Best for                        |
+| ---------------------- | ------------------------------------------ | ------------------------------- |
+| **Tribe (social)**     | Social validation from other users         | Social products, community apps |
+| **Hunt (information)** | Useful, surprising, or interesting content | News, education, productivity   |
+| **Self (mastery)**     | Progress, completion, skill advancement    | Learning, fitness, productivity |
+
+**Variable reward design principles:**
+
+1. Not every session delivers the same reward level — some are better than others
+2. The anticipation of the reward is as motivating as the reward itself
+3. Deliver the reward immediately after the action (not on the next session)
+4. Add occasional "jackpot" moments: unexpected larger rewards
+5. Never make the reward predictable (same reward every time → diminishing motivation)
+
+**Autonomy preservation:** During the reward phase, the user should feel in control, not constrained. If getting the reward requires watching an ad, completing a survey, or navigating required steps, the reward experience becomes aversive.
+
+**Reward examples by mechanic:**
+
+- **Streak system:** Streak counter increment + animation + occasional celebration (jackpot at 7/30/100 days)
+- **Progress bar:** Visual bar fill + "You're X% done" + next step suggestion
+- **Social feature:** Variable social feedback (likes, comments, replies — timing is unpredictable)
+- **Learning product:** Quiz result + "You got X/Y right" + occasional perfect score celebration
+
+---
+
+## Step 6: Design the investment layer
+
+**Goal:** Ensure users leave something behind after each session that makes the product more valuable on the next visit.
+
+Investment types to consider:
+
+| Type                       | Example                              | Value increase mechanism            |
+| -------------------------- | ------------------------------------ | ----------------------------------- |
+| **Data/personalization**   | Watched content, completed lessons   | Better recommendations next session |
+| **User-generated content** | Posts, photos, notes, projects       | History and portfolio building      |
+| **Social graph**           | Followers, connections, team members | Social switching cost               |
+| **Reputation**             | Badges, reviews, ratings, level      | Public identity investment          |
+| **Settings/configuration** | Custom workflows, saved preferences  | Painful to recreate                 |
+| **History/progress**       | Learning progress, activity log      | Loss if they leave                  |
+
+For the mechanic being designed, answer:
+
+- What does the user leave behind after completing the target behavior?
+- How does that accumulate over time?
+- What would they lose if they switched to a competitor?
+- Is the investment visible to the user (so they're aware of its value)?
+
+---
+
+## Step 7: Ethical check
+
+**Goal:** Verify the mechanic delivers genuine value to users and doesn't exploit psychological vulnerabilities.
+
+Answer each question honestly:
+
+1. **The thank-you test:** "If a user understood exactly what psychological mechanism this feature uses, would they thank us for designing it this way?"
+   - If yes: proceed
+   - If uncertain: redesign until yes
+
+2. **Value alignment:** Does the mechanic encourage behavior that genuinely improves the user's life or experience? Or does it maximize engagement at the expense of user wellbeing?
+   - Streak for learning a language: helps the user achieve their goal → proceed
+   - Streak for viewing ads: maximizes platform revenue without user benefit → do not ship
+
+3. **Anxiety test:** Will this mechanic cause anxiety or distress for users who can't maintain it?
+   - If yes: add opt-out, recovery mechanics, or reduce the stakes framing
+
+4. **Dark pattern check:** Does this mechanic make it harder to leave the product than easier to stay?
+   - Genuine retention: make the product so valuable users don't want to leave
+   - Dark pattern: hide cancel buttons, charge after free trial without clear warning, make account deletion difficult
+   - Dark patterns are off-limits regardless of retention impact
+
+5. **Regulatory check:** Does this mechanic involve gambling mechanics (loot boxes), target children, or create addictive loops with no opt-out?
+   - These require legal review before implementation
+
+---
+
+## Step 8: Define the measurement plan
+
+**Goal:** Define how you'll know if this mechanic is working.
+
+**Primary metric:**
+
+- What specific retention metric does this mechanic target?
+- What is the current baseline?
+- What is the target improvement (e.g., D7 retention from 22% to 28%)?
+- How long will you run the test before evaluating?
+
+**Measurement approach:**
+
+- A/B test: control (no mechanic) vs. treatment (mechanic enabled) — preferred
+- Cohort analysis: compare retention curves for users who engage with mechanic vs. those who don't
+- Note: cohort analysis has selection bias (users who engage with mechanic are already more motivated); A/B test is cleaner
+
+**Guardrail metrics:**
+
+- Monitor these to ensure the mechanic doesn't harm other user behaviors:
+  - Notification opt-out rate (rising opt-outs = spam signal)
+  - Session quality (time in productive feature / total time) — don't optimize for empty engagement
+  - Support ticket volume (streak anxiety complaints, etc.)
+  - NPS / user satisfaction scores
+
+**Leading indicators (check weekly):**
+
+- % of target users who engaged with the mechanic
+- Mechanic engagement rate (e.g., streak completion rate day-over-day)
+
+**Lagging indicator (check at 4/8/12 weeks):**
+
+- Primary retention metric vs. control group
+
+---
+
+## Step 9: Document and handoff
+
+**Goal:** Create a complete feature spec the team can implement.
+
+Feature spec template:
+
+```
+RETENTION MECHANIC: [Name]
+
+Psychological model: [Hook / Fogg / Habit Loop / SDT]
+Target behavior: [Specific action]
+Target user segment: [New / Returning / At-risk]
+Primary metric: [Metric] — Baseline: [X] — Target: [Y]
+
+TRIGGER:
+  Type: [Behavioral / Time-based / Calendar-based]
+  Channel: [Push / Email / In-app]
+  Timing: [Specific logic]
+  Copy: [Notification text with loss framing]
+
+ACTION PATH:
+  Steps from trigger to completion: [count]
+  Deep link target: [specific screen]
+  Friction removed: [what was simplified]
+
+REWARD:
+  Type: [Tribe / Hunt / Self]
+  Variable? [Yes / No — if no, explain why]
+  Jackpot moment: [Description]
+  Timing: [Immediate on completion]
+
+INVESTMENT:
+  What user leaves behind: [Description]
+  Value accumulation mechanism: [How it grows]
+
+ETHICAL REVIEW:
+  Thank-you test: [Pass / Fail — notes]
+  Value alignment: [Pass / Fail — notes]
+  Anxiety risk: [Low / Medium — mitigation]
+  Recovery mechanic: [If streak: streak freeze. If other: describe]
+
+MEASUREMENT:
+  Primary metric: [Metric]
+  Test approach: [A/B test / Cohort]
+  Test duration: [Weeks]
+  Guardrail metrics: [List]
+```