agileflow 3.4.3 → 4.0.0-alpha.10

package/content/plugins/planning/skills/agileflow-planning/references/sprint-planning-guide.md

@@ -0,0 +1,145 @@
+# Sprint Planning Guide
+
+**Load this when:** Running sprint planning, setting sprint goals, calculating capacity, or ordering the backlog.
+
+## Sprint Planning Structure
+
+```
+Total time: 1 hour per sprint week (2-week sprint = 2 hours max)
+
+Part 1 — What (30-50% of time)
+  - Product owner presents sprint goal
+  - Review top backlog items
+  - Clarify acceptance criteria
+  - Confirm stories are ready
+
+Part 2 — How (50-70% of time)
+  - Team pulls stories into sprint to capacity
+  - Break stories into tasks if needed
+  - Flag dependencies and blockers
+  - Confirm sprint goal commitment
+```
+
+---
+
+## Capacity Calculation
+
+```
+Raw capacity = team members × hours/day × sprint days
+
+Adjusted capacity = raw capacity
+  - planned time off (PTO, holidays)
+  - ceremonies (standups, planning, retro, review)
+  - planned non-feature work (on-call, support, tech debt)
+  - ramp-up factor for new team members
+
+Rule of thumb: 60–70% of raw capacity = realistic capacity
+```
+
+### Example (2-week sprint)
+
+```
+Team: 4 developers
+Raw: 4 × 8h × 10 days = 320 hours
+
+Deductions:
+  Ceremonies: 4 × 2h × 10 days = 80h (standups + misc)
+  Support rotation: 1 person × 0.25 FTE = 20h
+  PTO: 1 person × 1 day = 8h
+
+Adjusted: 320 - 108 = 212 dev-hours ≈ 65% utilization
+Points: 212h / 7h per point ≈ 30 points
+```
+
+---
+
+## Sprint Goal Framework
+
+A good sprint goal answers: **What business or user outcome will we deliver this sprint?**
+
+### Template
+
+```
+By end of sprint [N], we will [capability delivered]
+so that [user/business outcome].
+
+Key stories: [list 2–4 anchor stories]
+Success metric: [how we'll know we achieved it]
+```
+
+### Examples
+
+Good:
+
+> "By end of Sprint 14, users can invite team members and set their roles, so teams can onboard collaborators without involving support."
+
+Bad:
+
+> "Complete stories PROJ-45, PROJ-47, and PROJ-51."
+
+---
+
+## Backlog Ordering Criteria
+
+Score each story, order by composite score:
+
+| Criterion           | Weight | How to score                                   |
+| ------------------- | ------ | ---------------------------------------------- |
+| User/business value | 30%    | 1–5 (5 = highest impact)                       |
+| Urgency / deadline  | 25%    | 1–5 (5 = this sprint or miss commitment)       |
+| Risk reduction      | 20%    | 1–5 (5 = critical risk if not done)            |
+| Effort (inverse)    | 15%    | 5 = 1pt, 4 = 2pt, 3 = 3-5pt, 2 = 8pt, 1 = 13pt |
+| Dependencies        | 10%    | 5 = unblocks others, 1 = blocked by others     |
+
+**Weighted priority score = Σ(score × weight)**
+
+---
+
+## Story Readiness Checklist (INVEST)
+
+Before pulling a story into sprint planning, verify:
+
+| Letter | Criterion   | Check                                   |
+| ------ | ----------- | --------------------------------------- |
+| I      | Independent | Not blocked by another incomplete story |
+| N      | Negotiable  | Scope can flex; not a fixed spec        |
+| V      | Valuable    | Clear user or business value stated     |
+| E      | Estimable   | Team can estimate it (enough detail)    |
+| S      | Small       | Completable within one sprint           |
+| T      | Testable    | Clear acceptance criteria exist         |
+
+If any are missing — do not pull into sprint. Refine first.
+
+---
+
+## Sprint Commitment Rules
+
+- Commit to the **sprint goal**, not a list of stories
+- If sprint is at risk, protect the goal — negotiate scope of supporting stories
+- Never add scope mid-sprint without removing equivalent scope
+- Unfinished stories return to the top of the backlog for next sprint (re-estimate if needed)
+
+---
+
+## Common Sprint Planning Failures
+
+| Failure                     | Symptom                                   | Fix                                                     |
+| --------------------------- | ----------------------------------------- | ------------------------------------------------------- |
+| Overcommitment              | Stories spill every sprint                | Use 80% of velocity, not 100%                           |
+| No sprint goal              | Team has no compass when trade-offs arise | Write goal before pulling stories                       |
+| Unrefined stories in sprint | Estimation errors, mid-sprint discovery   | Enforce INVEST checklist                                |
+| No task breakdown           | Stories "in progress" for days            | Break into tasks <1 day each during planning            |
+| Planning == assigning       | Engineers don't know context              | Stories are chosen by team, not assigned by manager     |
+| Skipping retrospective data | Repeat same mistakes                      | Review previous retro action items at start of planning |
+
+---
+
+## Sprint Metrics to Review at Planning Start
+
+| Metric                    | What it tells you                 |
+| ------------------------- | --------------------------------- |
+| Velocity (last 3 sprints) | Baseline for capacity planning    |
+| Story completion rate     | Are we finishing what we start?   |
+| Carryover %               | How much spills sprint to sprint? |
+| Defect rate               | Are we shipping quality?          |
+| Retro action item status  | Are we improving?                 |

package/content/plugins/planning/skills/agileflow-planning/workflows/impact.md

@@ -0,0 +1,63 @@
+# Impact Workflow — Code Change Impact Analysis
+
+**Triggers:** "what will this change break", "impact analysis", "what files depend on this", "check for regressions before I merge", "what else might be affected", "dependency graph for [file]"
+
+**Goal:** Build a dependency graph for changed files, detect breaking changes, find related tests, and generate a risk-scored impact report so the user knows exactly what to test before merging.
+
+## Inputs needed
+
+| Input         | Required | How to get it                                |
+| ------------- | -------- | -------------------------------------------- |
+| changed files | No       | Auto-detected from `git diff` against `main` |
+| base branch   | No       | Default: `main`                              |
+| run tests     | No       | Ask the user                                 |
+
+## Steps
+
+1. Detect changed files. Run `git diff main --name-only`. If no changes are staged or if the user specified particular files, use those. If the working tree is clean, ask: "Which files should I analyze?"
+
+2. For each changed file, find what imports it (direct callers). Then find what imports those callers (indirect callers — 2 levels max). Show the dependency chain as a table with file paths and the line numbers where they import the changed file.
+
+3. Detect breaking changes in each modified file by comparing the current version to the base branch version:
+   - Function parameters added, removed, or reordered
+   - Exported type or interface modifications
+   - Return type changes
+   - Removed exports or renamed exports
+     Label each: **Breaking** (callers will likely fail) or **Non-breaking** (additive change only).
+
+4. Find related tests using both pattern-matching (test files that reference the changed file by name) and directory proximity (tests in the same module area).
+
+5. Assign risk scores:
+   - **Critical**: breaking changes with identified callers
+   - **Recommended**: non-breaking changes in highly-used files
+   - **Optional**: test files in the vicinity, low likelihood of impact
+
+6. Present the impact report. Example format:
+
+   ```
+   Changed: src/auth/session.ts
+   Direct callers (3): src/api/users.ts, src/middleware/auth.ts, src/pages/login.tsx
+   Indirect callers (5): ...
+   Breaking changes: parameter type in getUserSession() changed
+   Related tests: tests/auth/session.test.ts (critical), tests/api/users.test.ts (recommended)
+   ```
+
+7. Ask: [A] Run the critical and recommended tests now, [B] Show me the full caller list for a specific file, [C] I'll run tests myself — just give me the list.
+
+8. If running tests, execute them and report the results. Flag any new failures compared to the base branch.
+
+## Output
+
+Impact report with dependency graph (2 levels), breaking change detection, related tests by risk level (Critical / Recommended / Optional). Optional: test run with pass/fail results.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/planning/skills/agileflow-planning/workflows/rpi.md

@@ -0,0 +1,104 @@
+# RPI Workflow — Research → Plan → Implement
+
+**Triggers:** "use the RPI workflow", "let's do Research Plan Implement", "I need to think this through carefully", "complex task I don't fully understand yet", "brownfield feature in unfamiliar code", "RPI for [feature]"
+
+**Goal:** Guide a complex task through three sequential phases — Research, Plan, Implement — each producing a compressed artifact that seeds the next phase, preserving context quality across conversation boundaries.
+
+## Inputs needed
+
+| Input            | Required | How to get it                            |
+| ---------------- | -------- | ---------------------------------------- |
+| task description | Yes      | Ask if not provided                      |
+| starting phase   | No       | Default: auto-detect based on complexity |
+
+## Complexity assessment
+
+Before starting, assess the task complexity:
+
+| Level       | Signs                         | Approach                         |
+| ----------- | ----------------------------- | -------------------------------- |
+| Trivial     | Typo, config tweak            | Skip RPI — just do it            |
+| Simple      | Single file, clear path       | Plan → Implement (skip Research) |
+| Moderate    | Multi-file, known patterns    | Plan → Implement                 |
+| Complex     | Brownfield, unfamiliar code   | Full Research → Plan → Implement |
+| Exploratory | Unknown territory, multi-repo | Full RPI with iteration          |
+
+## Steps
+
+### Phase 0: Triage
+
+1. Read the task. Assess complexity using the table above. If the task is trivial or simple, say so and suggest a more direct approach. For complex or exploratory tasks, proceed with full RPI.
+
+2. Ask: [A] Full RPI (Research → Plan → Implement), [B] Skip to Plan (I understand the codebase area), [C] Skip to Implement (I have a plan already).
+
+---
+
+### Phase 1: RESEARCH
+
+3. Explore the relevant codebase areas without making changes. Read the files that will be affected. Understand existing patterns, data structures, dependencies, and constraints.
+
+4. Identify unknowns: things that need external research (unfamiliar APIs, library patterns, architectural questions). Use the research import workflow if external lookups are needed.
+
+5. Produce the Research Artifact — a compressed markdown summary:
+
+   ```
+   ## Research Summary: [Task]
+   Codebase findings: [key patterns, files, constraints]
+   Unknowns resolved: [what was looked up]
+   Approach options: [2–3 options considered]
+   Recommended approach: [chosen option + rationale]
+   ```
+
+   Save to `docs/10-research/<task-slug>-research.md`.
+
+6. Ask: [A] Start a new conversation for the Plan phase (recommended — fresh context), [B] Continue in this conversation.
+
+---
+
+### Phase 2: PLAN
+
+7. Read the Research Artifact. Design the implementation in detail:
+   - Files to create or modify (specific paths)
+   - Order of changes
+   - How to handle edge cases
+   - Test strategy
+
+8. Produce the Plan Artifact:
+
+   ```
+   ## Implementation Plan: [Task]
+   Files to change: [list with purpose]
+   Step-by-step: [numbered implementation steps]
+   Tests: [what to write and when]
+   Risk: [breaking changes, migration needs]
+   ```
+
+   Save to `docs/<task-slug>-plan.md`.
+
+9. Ask: [A] Start a new conversation for the Implement phase (recommended), [B] Continue in this conversation.
+
+---
+
+### Phase 3: IMPLEMENT
+
+10. Read the Plan Artifact. Execute the plan step by step. After each step, run the relevant tests. Do not skip steps or add scope.
+
+11. When all steps are complete, run the full test suite. Fix any failures before declaring done.
+
+12. Ask: [A] Run the story audit to verify AC coverage, [B] Create the PR.
+
+## Output
+
+Research artifact, Plan artifact, and implemented code — each in a separate, high-quality context. Context health is monitored throughout; the user is warned if utilization exceeds 40%.
+
+## Fallbacks
+
+**If interactive prompts (AskUserQuestion) are unavailable:**
+Present options as a numbered list in your response. Ask the user to reply with a number. Example:
+
+```
+How would you like to proceed?
+1. Save and continue
+2. Review before saving
+3. Discard
+```

package/content/plugins/psychology/plugin.yaml

@@ -0,0 +1,14 @@
+id: psychology
+name: Psychology & Retention
+description: Apply behavioral psychology and UX research to improve user retention.
+version: 1.0.0
+enabledByDefault: false
+cannotDisable: false
+depends: []
+provides:
+  skills:
+    - id: agileflow-retention
+      dir: skills/agileflow-retention
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/psychology/skills/agileflow-retention/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: agileflow-retention
+version: 1.0.0
+category: agileflow/psychology
+description: |
+  Use when the user wants to improve user retention, reduce churn,
+  increase engagement, design habit-forming features, or apply
+  behavioral psychology to product decisions. Draws on evidence-based
+  models (Hook Model, Fogg Behavior Model, Habit Loop) and competitor
+  patterns from high-retention products.
+triggers:
+  keywords:
+    - retention
+    - engagement
+    - habit
+    - keep users
+    - churn
+    - activation
+    - onboarding flow
+    - user psychology
+    - sticky features
+    - daily active users
+    - streak
+    - progress bar
+    - notification strategy
+    - user motivation
+  priority: 50
+  exclude:
+    - data retention (legal)
+    - retention policy
+    - memory retention
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/retention.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Retention
+
+Applies evidence-based behavioral psychology to product design decisions — improving user retention, reducing churn, increasing engagement, and building habit-forming features that users actually want.
+
+## When this skill activates
+
+- User wants to reduce churn or improve D1/D7/D30 retention rates
+- User is designing or auditing onboarding and activation flows
+- User asks how to make a feature "sticky" or build habits
+- User wants to design a streak system, notification strategy, progress indicator, or social feature
+- User wants to understand why users drop off and what to do about it
+- User asks about user psychology, behavioral economics, or motivation design
+- Should NOT activate for data retention policies, legal retention requirements, or memory science
+
+## What this skill does
+
+1. Identify which psychological model fits the user's retention challenge
+2. Diagnose the current funnel: where are users dropping off and why?
+3. Map the product against the Hook Model, Fogg Behavior Model, and Habit Loop
+4. Recommend specific mechanics with evidence from high-retention products
+5. Design the trigger, action, reward, and investment for new retention features
+6. Apply an ethical check: is this genuine value or dark pattern manipulation?
+7. Define the measurement framework: what metric proves the mechanic works?
+
+## The three core behavioral models
+
+### 1. BJ Fogg's Behavior Model (B=MAP)
+
+Behavior occurs when **Motivation**, **Ability**, and **Prompt** converge at the same moment.
+
+The key insight: you don't need high motivation if you increase ability (reduce friction). You don't need high ability if you catch a user at peak motivation. The prompt (trigger) must fire at exactly the right moment.
+
+**Application:** Audit each step in your activation flow for where motivation drops or where ability is too low. The fix is either to increase motivation (social proof, progress feedback) or to reduce friction (fewer steps, defaults, auto-fill).
+
+See `references/psychology-models.md` for the full model detail.
+
+### 2. Nir Eyal's Hook Model
+
+**Trigger → Action → Variable Reward → Investment**
+
+The Hook Model (from "Hooked", 2014) explains how products build unprompted usage habits. Each completed hook cycle increases habit strength. The goal over time is to replace external triggers (notifications) with internal triggers (emotional cues like boredom or FOMO).
+
+**Application:** Map your product against all four phases. Most products have triggers and actions. Few invest in variable rewards and even fewer design for investment — but investment is what makes users feel they have something to lose by leaving.
+
+See `references/psychology-models.md` for the full model detail.
+
+### 3. Duhigg's Habit Loop
+
+**Cue → Routine → Reward → Craving**
+
+Once a habit loop is established, the brain disengages its prefrontal cortex and the basal ganglia runs the routine automatically. The craving is what drives repetition — users don't return for the reward itself; they return in anticipation of it.
+
+**Application:** Identify the cue your product can "own" (a time of day, an emotion, an activity context), design the routine to be frictionless, deliver the reward immediately and sometimes variably.
+
+See `references/psychology-models.md` for the full model detail.
+
+### 4. Self-Determination Theory (SDT)
+
+Three basic psychological needs drive intrinsic motivation: **Autonomy**, **Competence**, **Relatedness**. Products that satisfy all three build the deepest, most resilient retention because users want to be there — not because they're trapped.
+
+**Important warning:** Extrinsic rewards (points, badges, coins) can crowd out intrinsic motivation for activities users already find interesting. Use gamification carefully.
+
+See `references/psychology-models.md` for the full model detail.
+
+## Key retention mechanics
+
+| Mechanic                 | Psychological basis                       | Best example                               |
+| ------------------------ | ----------------------------------------- | ------------------------------------------ |
+| Streaks                  | Loss aversion (Kahneman & Tversky, 1979)  | Duolingo — 2.4× retention at 30-day streak |
+| Progress bars            | Zeigarnik Effect + commitment consistency | LinkedIn profile completeness              |
+| Variable rewards         | Skinner's variable ratio schedule (1938)  | Instagram like reveals, Wordle             |
+| Social proof             | Cialdini's influence principles (1984)    | Airbnb "usually books within 24 hours"     |
+| Personalized onboarding  | Aha moment optimization                   | Facebook: 7 friends in 10 days             |
+| Behavioral notifications | Urban Airship data (2016): 2–5× lift      | Triggered > scheduled blasts               |
+| Endowed progress         | Nunes & Dreze loyalty card study (2006)   | Pre-filled stamp cards                     |
+| Loss aversion triggers   | Kahneman: losses felt 2× more than gains  | Duolingo streak saver notification         |
+
+See `references/retention-patterns.md` for full implementation guides with evidence.
+
+## Competitor patterns to learn from
+
+| Product  | Key mechanic                   | Measurable outcome                                |
+| -------- | ------------------------------ | ------------------------------------------------- |
+| Duolingo | Streaks + XP + leagues         | ~50% DAU/MAU ratio                                |
+| LinkedIn | Profile completeness bar       | Measurably higher registration completion         |
+| Slack    | Unreads + reactions + channels | Teams sending 2,000+ messages are deeply retained |
+| Strava   | Social feed + kudos + segments | Activity habit reinforcement                      |
+| Spotify  | Discover Weekly + Wrapped      | Reduces genre fatigue churn                       |
+| Notion   | Templates + public pages       | Lower activation friction                         |
+
+See `references/competitor-analysis.md` for detailed breakdowns of what each product does and why it works.
+
+## Opening discovery flow
+
+When invoked without a specific task, ask one focused question:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What retention challenge are you working on?",
+    "header": "Retention focus",
+    "multiSelect": false,
+    "options": [
+      {"label": "Audit my existing product for retention gaps (Recommended)", "description": "Map your current product against the Hook Model, Fogg, and Habit Loop — get a prioritized gap list"},
+      {"label": "Design a new retention mechanic (streak, progress, notifications, etc.)", "description": "Choose a mechanic, design its trigger/reward/investment, and define how to measure it"},
+      {"label": "Improve my onboarding and activation flow", "description": "Identify the 'aha moment' and redesign the path to reach it faster"},
+      {"label": "Analyze competitor retention strategies", "description": "Deep-dive on how a specific high-retention product keeps users coming back"},
+      {"label": "Understand the psychology behind a specific mechanic", "description": "Get the research, models, and evidence behind streaks, variable rewards, social proof, etc."}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+**Route based on answer:**
+
+| Answer                 | Next action                                                                 |
+| ---------------------- | --------------------------------------------------------------------------- |
+| Audit existing product | Follow `workflows/retention-audit.md`                                       |
+| Design new mechanic    | Follow `workflows/design-retention-feature.md`                              |
+| Onboarding/activation  | Start with aha moment identification, then Fogg audit                       |
+| Competitor analysis    | Load `references/competitor-analysis.md`                                    |
+| Psychology explanation | Load `references/psychology-models.md` + `references/retention-patterns.md` |
+
+## Ethical framework
+
+Retention mechanics exist on a spectrum from **genuine value** to **manipulation**:
+
+**Genuine value:** The mechanic improves the user's actual experience. Streaks work for Duolingo because they help users actually learn a language. Users would thank you for designing this.
+
+**Engagement bait:** The mechanic keeps users in the product without delivering real value. Infinite scroll with algorithmically outraged content keeps users engaged but doesn't serve them.
+
+**Dark patterns:** The mechanic exploits psychological vulnerabilities to extract value from users (dark subscriptions, artificial urgency, hidden cancellations).
+
+For every mechanic you design, apply this test: **"Would a user who understood exactly what you were doing thank you for it?"**
+
+If yes: ship it.
+If no: redesign until the answer is yes, or don't build it.
+
+## Retention metric hierarchy
+
+Define your primary retention metric before designing any mechanic:
+
+| Metric                | Definition                                   | Best for                            |
+| --------------------- | -------------------------------------------- | ----------------------------------- |
+| **D1 retention**      | % of day-1 users who return on day 2         | Mobile apps, early activation       |
+| **D7 retention**      | % of week-1 users who return on day 8        | Apps requiring habit formation      |
+| **D30 retention**     | % of month-1 users who return on day 31      | SaaS, subscription products         |
+| **DAU/MAU ratio**     | % of monthly users who are also daily users  | Engagement depth (40%+ = excellent) |
+| **Session frequency** | Average sessions per user per week           | Communication, utility apps         |
+| **Churn rate**        | % of active users who stop using in a period | Subscription products               |
+
+Always tie mechanics to a specific metric. "Improve engagement" is not a goal; "increase D7 retention from 22% to 35%" is a goal.
+
+## Quality checklist
+
+Before shipping a retention mechanic:
+
+- [ ] Target metric is defined and baselined
+- [ ] Psychological model is identified (Hook / Fogg / Habit Loop / SDT)
+- [ ] Trigger is designed (external → internal over time)
+- [ ] Friction in the action phase is minimized (Fogg's 6 simplicity factors)
+- [ ] Reward is variable or surprising (not predictable)
+- [ ] Investment layer designed (user leaves something behind that increases value)
+- [ ] Ethical test passed ("Would users thank you for this?")
+- [ ] Measurement plan exists (A/B test or cohort analysis)
+- [ ] Feature does not exploit psychological vulnerabilities
+
+## Self-improving learnings
+
+`_learnings/retention.yaml` records:
+
+- Product type and primary retention metric in use
+- Which psychological models the team has found most applicable
+- Mechanic implementations that have been tried and their outcomes
+- Team's ethical bar for retention mechanics
+
+Apply on invocation; update on correction with confidence (high / medium / low).
+
+## Integration
+
+- **agileflow-epic-planner** — a retention initiative becomes an epic with measurable success metrics (D1/D7/D30 retention, streak rate, notification CTR)
+- **agileflow-story-writer** — individual retention mechanics become user stories with acceptance criteria tied to specific behavioural metrics
+- **agileflow-pr-reviewer** — notifications, behavioural triggers, and urgency patterns get a second review to confirm they don't cross into dark patterns
+- **agileflow-ideation** — use ideation before retention design to surface engagement feature opportunities; retention applies behavioural psychology to the top ideas
+- **agileflow-research** — gather evidence-based engagement patterns, platform benchmark DAU/MAU ratios, and competitor onboarding flows before designing retention mechanics
+- **agileflow-engineering** — delegate implementation of habit loops, notification systems, streak tracking, and progress visualisation
+- **agileflow-ads** — align retention campaign strategy (win-back emails, re-engagement ads) with in-product retention mechanics for a coherent lifecycle
+- **agileflow-planning** — use planning to prioritise retention initiatives against acquisition work; retention ROI (lower CAC payback) is a planning input
+- **agileflow-council** — convene before designing controversial retention mechanics (social pressure, FOMO triggers) to evaluate ethical trade-offs
+
+## References
+
+Load these files when you need deeper context:
+
+| File                                | When to load                                                                                                                                                     |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/psychology-models.md`   | Understanding the theoretical foundation — Fogg B=MAP, Hook Model, Habit Loop, SDT — with citations and application guidance                                     |
+| `references/retention-patterns.md`  | Specific mechanics with evidence: streaks, progress bars, variable rewards, social proof, endowed progress — each with study references and implementation steps |
+| `references/competitor-analysis.md` | How high-retention products (Duolingo, LinkedIn, Slack, Strava, Spotify, Notion) implement these mechanics in practice                                           |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                                    | When to follow                                                                                                                                   |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `workflows/retention-audit.md`          | User wants to audit their existing product for retention gaps — maps against Hook Model, Fogg, Habit Loop, and specific mechanics                |
+| `workflows/design-retention-feature.md` | User wants to design a new retention mechanic — from model selection through trigger design, reward structure, investment layer, and measurement |