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

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

@@ -0,0 +1,259 @@
+# Workflow: Retention Audit
+
+**Follow this when:** the user wants to audit their existing product for retention gaps, understand why users are churning, or get a prioritized list of retention improvements.
+
+**Time estimate:** 60–120 minutes for a thorough audit. Can be done in 20 minutes for a quick scan.
+
+**Output:** A prioritized gap list with specific recommendations, organized by psychological model and impact vs. effort.
+
+---
+
+## Before you start
+
+Ask the user for the following information (or infer from context):
+
+1. What type of product is this? (mobile app, SaaS, consumer web, marketplace, etc.)
+2. What is the primary retention metric? (D1/D7/D30 retention, DAU/MAU, churn rate, session frequency)
+3. What are the current baseline numbers for that metric?
+4. Where in the funnel is the biggest drop-off? (acquisition → activation → retention → revenue → referral)
+5. Do they have a defined "aha moment" — a specific action that correlates with long-term retention?
+
+If the user doesn't know the answer to questions 3–5, note that identifying these is part of the audit.
+
+---
+
+## Step 1: Define and baseline the retention metric
+
+**Goal:** Know exactly what you're measuring before recommending any mechanic.
+
+Actions:
+
+1. Identify the primary retention metric for this product type:
+   - Mobile consumer app → D1 / D7 / D30 retention
+   - SaaS / subscription → D30 / D90 retention, monthly churn rate
+   - Daily-use utility (messaging, email) → DAU/MAU ratio
+   - Social / community product → D7 / session frequency per week
+2. Get the current baseline number if available
+3. Identify the benchmark for the product category (e.g., D30 retention > 25% is good for mobile apps; DAU/MAU > 20% is good for most products)
+4. Note the gap between current and benchmark
+
+**Output:** "We're measuring D7 retention. Current: 18%. Benchmark for this category: 30%. Gap: 12 percentage points."
+
+---
+
+## Step 2: Map the current user journey
+
+**Goal:** Understand the full path from signup to retained user, and find where most users exit.
+
+Actions:
+
+1. Walk through the product from a new user's perspective (or ask the user to describe it)
+2. Map each step: Signup → Onboarding → First value → Return visit → Habit
+3. Note which steps require decisions, effort, or motivation
+4. Identify where users most commonly drop off (ask for data if available; otherwise estimate from product knowledge)
+5. Identify the "aha moment" — the specific action that signals a user will be retained
+   - If undefined: ask "What do your most retained users do in their first week that casual users don't?"
+   - Common examples: Facebook (7 friends in 10 days), Slack (2,000 messages exchanged), Dropbox (first file uploaded)
+
+**Output:** A journey map with drop-off points marked and the aha moment identified (or TBD with a research recommendation).
+
+---
+
+## Step 3: Audit against the Hook Model
+
+**Goal:** Assess whether the product has a functional habit loop.
+
+For each phase, score 1–5 (1 = absent/broken, 5 = excellent):
+
+**Trigger audit**
+
+- What external triggers exist? (push notifications, emails, badges)
+- Are these triggers behavioral (user-action-triggered) or scheduled (marketing calendar)?
+- What internal trigger is the product trying to own? (boredom, FOMO, loneliness, anxiety, curiosity)
+- Do users report opening the app without a specific external trigger? (if yes: internal triggers are forming)
+- Score: `/5`
+
+**Action audit**
+
+- What is the single most important action the product wants users to take?
+- How many steps separate the external trigger from that action?
+- What are the friction points in reaching that action? (login walls, decision points, loading time)
+- Score: `/5`
+
+**Variable reward audit**
+
+- What reward does the user receive after completing the core action?
+- Is the reward variable or predictable?
+- Which reward type does it represent: Tribe (social), Hunt (information), or Self (mastery)?
+- Does the user feel in control during the reward phase, or constrained?
+- Score: `/5`
+
+**Investment audit**
+
+- What does the user leave behind after each session?
+- Does that stored value increase over time? (e.g., recommendations get better, more followers, more content)
+- Does the user feel the product would be painful to leave because of what they've invested?
+- Score: `/5`
+
+**Hook Model total:** `/20`
+
+Interpretation:
+
+- 16–20: Strong habit loop. Focus on growth, not retention mechanics.
+- 10–15: Moderate loop. Specific phases need work. Prioritize lowest-scoring phase.
+- Under 10: Weak or broken loop. Retention mechanics are unlikely to work until the core loop is fixed.
+
+---
+
+## Step 4: Audit against the Fogg Behavior Model
+
+**Goal:** Find where motivation or ability is insufficient in critical flows.
+
+**For each critical action (onboarding completion, first core action, first return visit):**
+
+1. **Motivation audit:**
+   - Is the value proposition clear before the user is asked to take this action?
+   - Is there social proof, urgency, or benefit framing near the action?
+   - Would a user with moderate motivation still take this action?
+   - Identify specific moments where motivation is likely to drop
+
+2. **Ability audit:**
+   - Walk through each step: how long does it take? how much does it cost? how much cognitive load?
+   - Are there steps that require decisions without enough information to decide well?
+   - Are there unnecessary steps that could be removed or defaulted?
+   - Apply Fogg's 6 simplicity factors to the critical path
+
+3. **Prompt audit:**
+   - Are users prompted at the right moment, or does the prompt fire when motivation is low?
+   - Are prompts generic (scheduled) or behavioral (triggered by user state)?
+   - Is there a facilitator prompt catching users who are mid-flow and almost done?
+
+**Output:** List of specific friction points and motivation drops, with the step in the flow where each occurs.
+
+---
+
+## Step 5: Notification strategy audit
+
+**Goal:** Evaluate whether the notification strategy supports or undermines retention.
+
+Questions to answer:
+
+1. How many notification types exist? List them all.
+2. For each: is it triggered by user behavior or by a marketing schedule?
+3. What is the average weekly notification count per user?
+4. What is the notification opt-out rate? (>20% is a warning sign)
+5. Are there "streak at risk" or loss-aversion notifications?
+6. Are there recovery mechanics for users who have lapsed?
+
+Score each notification type:
+
+- Behavioral trigger (high relevance): strong keep
+- Milestone trigger (user's own progress): keep
+- Social trigger (friend activity): keep
+- Marketing/scheduled blast: reduce or eliminate
+
+**Output:** Notification audit with keep/improve/remove recommendation for each type.
+
+---
+
+## Step 6: Identify the keystone habit
+
+**Goal:** Find the single behavior that, if habitual, makes everything else in the product stick.
+
+Questions:
+
+1. What is the behavior that your most retained users do that casual users don't?
+2. What is the minimum frequency of that behavior that predicts long-term retention?
+3. Is the product designed to make that behavior frictionless and rewarding?
+4. Is there an anchor (existing routine) that could trigger this behavior?
+
+**Output:** The keystone habit, current state (frictionless vs. too much friction), and recommended design change.
+
+---
+
+## Step 7: Score the retention mechanics inventory
+
+**Goal:** Check which mechanics exist and how well they're implemented.
+
+For each mechanic, score: Missing (0) / Exists but weak (1) / Well-implemented (2):
+
+| Mechanic                                  | Present? | Quality | Notes |
+| ----------------------------------------- | -------- | ------- | ----- |
+| Streaks                                   |          |         |       |
+| Progress bars / completion                |          |         |       |
+| Variable rewards                          |          |         |       |
+| Social proof                              |          |         |       |
+| Personalized onboarding / aha moment path |          |         |       |
+| Behavioral notifications                  |          |         |       |
+| Endowed progress                          |          |         |       |
+| Loss aversion mechanics                   |          |         |       |
+| Social features / relatedness             |          |         |       |
+| Investment mechanics                      |          |         |       |
+
+**Mechanics score:** `/20`
+
+---
+
+## Step 8: Synthesize findings and prioritize
+
+**Goal:** Create a prioritized gap list the team can act on.
+
+Prioritization framework:
+
+- **Impact:** How much would fixing this improve the primary retention metric? (H/M/L)
+- **Effort:** How much engineering and design work is required? (H/M/L)
+- **Priority:** High impact + low effort = do first. High impact + high effort = plan as a project. Low impact = deprioritize.
+
+**Priority 1 (do immediately):** Low effort, high impact
+
+- Typically: fixing a broken notification trigger, adding loss-aversion framing to an existing notification, adding a streak recovery mechanic, reducing friction in a critical flow
+
+**Priority 2 (plan as a feature):** High impact, moderate/high effort
+
+- Typically: redesigning onboarding around aha moment, adding streak system, redesigning reward phase
+
+**Priority 3 (nice to have):** Low impact or low confidence
+
+- Typically: social proof additions, gamification experiments, investment mechanic improvements
+
+---
+
+## Output format
+
+Structure the audit output as:
+
+```
+RETENTION AUDIT SUMMARY
+========================
+
+Product: [name]
+Primary metric: [metric]
+Current baseline: [number]
+Category benchmark: [number]
+Gap: [gap]
+
+HOOK MODEL SCORE: [X/20]
+  Trigger: [X/5] — [key finding]
+  Action: [X/5] — [key finding]
+  Variable Reward: [X/5] — [key finding]
+  Investment: [X/5] — [key finding]
+
+FOGG AUDIT: [2–3 key friction points]
+
+NOTIFICATION AUDIT: [summary]
+
+KEYSTONE HABIT: [identified or TBD with recommendation]
+
+MECHANICS INVENTORY: [X/20]
+
+PRIORITY 1 GAPS (do immediately):
+  1. [Specific recommendation] — expected impact: [H/M/L] — effort: [H/M/L]
+  2. ...
+
+PRIORITY 2 GAPS (plan as features):
+  1. [Specific recommendation]
+  2. ...
+
+PRIORITY 3 (nice to have):
+  1. ...
+```

package/content/plugins/refactoring/plugin.yaml

@@ -0,0 +1,14 @@
+id: refactoring
+name: Refactoring
+description: Safe refactoring with impact analysis and test-first verification.
+version: 1.0.0
+enabledByDefault: false
+cannotDisable: false
+depends: []
+provides:
+  skills:
+    - id: agileflow-refactor
+      dir: skills/agileflow-refactor
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/refactoring/skills/agileflow-refactor/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: agileflow-refactor
+version: 1.0.0
+category: agileflow/refactoring
+description: |
+  Use when the user wants to improve existing code without changing its
+  observable behaviour. Applies safe refactoring patterns — extract
+  method/class, simplify conditionals, remove dead code, rename for
+  clarity — with an impact analysis and test-gate verification before
+  any change is made.
+triggers:
+  keywords:
+    - refactor
+    - clean up
+    - extract
+    - simplify
+    - too complex
+    - technical debt
+    - dead code
+    - rename
+    - restructure
+    - improve readability
+    - this is a mess
+    - hard to understand
+    - duplicate code
+    - god class
+    - long method
+  priority: 50
+  exclude:
+    - refactor to a new framework (migration, not refactoring)
+    - extract requirements (product management context)
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/refactor.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow Refactor
+
+Safe, systematic refactoring with impact analysis, test gates, and incremental change — improves code quality without breaking behaviour.
+
+## When this skill activates
+
+- User wants to clean up, simplify, or restructure code
+- User identifies technical debt or hard-to-maintain code
+- User wants to extract a reusable module or function
+- User says a function or class is "too complex" or "too long"
+- User wants to remove dead code or duplicate logic
+- User wants to rename for clarity
+- User is preparing code for a feature addition (make it easy to change, then change it)
+
+## Opening discovery flow
+
+**When invoked without a specific target, ask once to understand scope and intent.**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What would you like to refactor?",
+    "header": "Refactoring target",
+    "multiSelect": false,
+    "options": [
+      {"label": "A specific function or method that's too long or complex (Recommended)", "description": "Paste the function and I'll suggest extractions, simplifications, and naming improvements"},
+      {"label": "A class or module with too many responsibilities", "description": "Point me at the file — I'll identify which responsibilities should move to their own class"},
+      {"label": "Duplicate code across multiple files", "description": "Show me the duplication and I'll design a shared abstraction"},
+      {"label": "Clean up dead code or unused exports", "description": "I'll analyse the codebase for unused functions, variables, and modules"},
+      {"label": "Rename for clarity (variables, functions, files)", "description": "Tell me what feels poorly named and I'll suggest better names with impact analysis"},
+      {"label": "Reduce cyclomatic complexity in a function", "description": "I'll restructure conditionals using guard clauses, early returns, and strategy pattern"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+## Refactoring principles
+
+### 1. Tests first
+
+**Never refactor without a test safety net.** If the code doesn't have tests, write characterisation tests before touching anything.
+
+> "Make it easy to change, then change it."
+
+```
+Step 1: Write/confirm tests exist → they pass
+Step 2: Refactor
+Step 3: Tests still pass → behaviour preserved
+```
+
+If tests don't exist: offer to write them first (use `agileflow-test-writer`), or at minimum characterise the current behaviour.
+
+### 2. One refactoring at a time
+
+Don't rename AND restructure AND extract in one change. Small, focused refactors are safer and easier to review. Each step should:
+
+- Be independently committtable
+- Leave the tests green
+- Do exactly one kind of improvement
+
+### 3. Boy Scout Rule
+
+"Always leave the code a little better than you found it." When touching a file for another purpose, fix obvious issues:
+
+- Rename a confusing variable
+- Extract a magic number to a constant
+- Remove a dead branch
+
+But don't go beyond what's proportionate to the change at hand.
+
+### 4. No behaviour changes
+
+A refactoring, by definition, does not change observable behaviour. If the change would alter:
+
+- Function inputs/outputs
+- Error types thrown
+- Side effects
+- Performance characteristics in a user-visible way
+
+...then it is not a pure refactoring — it is a feature change. Flag this to the user.
+
+## Impact analysis before every refactoring
+
+Before making any change, assess:
+
+| Question                                                        | Why it matters                          |
+| --------------------------------------------------------------- | --------------------------------------- |
+| What calls this function/uses this module?                      | Determines blast radius                 |
+| Are there tests covering this code?                             | Determines safety of the change         |
+| Is this a public API (used by consumers outside this codebase)? | Determines if this is a breaking change |
+| Are there feature flags or A/B tests touching this code?        | Could change which variant runs         |
+| Are there any type definitions that reference this?             | Types may need updating too             |
+
+Run a quick search before refactoring:
+
+- Find all usages: `grep -r "functionName" src/`
+- Find all imports: `grep -r "from './module'" src/`
+- Check for dynamic calls: `functionName\(` as a pattern
+
+## Common refactoring patterns
+
+See `references/refactoring-patterns.md` for the full catalogue. Quick reference:
+
+| Pattern                               | When to apply                                              |
+| ------------------------------------- | ---------------------------------------------------------- |
+| Extract function                      | Function > 20 lines, or section has a clear single purpose |
+| Extract class                         | Class has > 2 responsibilities, or file > 300 lines        |
+| Replace conditional with guard clause | Nested if/else with happy path buried in conditions        |
+| Replace magic number with constant    | Numeric literal used without explanation                   |
+| Extract variable                      | Complex expression used more than once                     |
+| Rename for clarity                    | Variable/function name doesn't describe what it does       |
+| Dead code removal                     | Function never called; variable never read                 |
+| Consolidate duplicate conditionals    | Same condition checked in multiple places                  |
+| Replace inheritance with composition  | Subclass only uses 10% of the parent's interface           |
+| Introduce parameter object            | Function takes > 4 parameters                              |
+
+## Code smell signals
+
+| Smell                      | Typical pattern                                         | Refactoring to apply                           |
+| -------------------------- | ------------------------------------------------------- | ---------------------------------------------- |
+| Long method                | > 30 lines                                              | Extract function                               |
+| Large class                | > 300 lines or > 5 public methods                       | Extract class                                  |
+| Duplicate code             | Same block in 2+ places                                 | Extract function or module                     |
+| Long parameter list        | > 4 parameters                                          | Introduce parameter object                     |
+| Deeply nested conditionals | > 3 levels of nesting                                   | Guard clauses, early returns                   |
+| Magic numbers              | `if (status === 3)`                                     | Named constant `if (status === ORDER_SHIPPED)` |
+| Dead code                  | Function defined but never called                       | Delete (with a search to confirm)              |
+| Inconsistent naming        | `getUser`, `fetchAccount`, `loadProfile` for same thing | Normalise naming convention                    |
+| God object                 | One class doing everything                              | Extract multiple focused classes               |
+| Shotgun surgery            | One change requires edits in 10 files                   | Consolidate into a single place                |
+
+## Refactoring safety checklist
+
+See `references/safety-checks.md` for the full checklist. Before any refactoring:
+
+- [ ] Tests exist and pass
+- [ ] Impact analysis complete (know who calls this)
+- [ ] Not a public API without a deprecation plan
+- [ ] Change is scoped to one pattern at a time
+- [ ] Can be committed independently (doesn't depend on other uncommitted changes)
+
+After refactoring:
+
+- [ ] Tests still pass
+- [ ] No new linting errors introduced
+- [ ] PR diff is readable (reviewer can understand what changed and why)
+- [ ] Commit message describes the refactoring pattern used
+
+## SOLID principles as refactoring targets
+
+| Principle                   | Violation signal                                    | Refactoring                         |
+| --------------------------- | --------------------------------------------------- | ----------------------------------- |
+| **S** Single Responsibility | Class does X and Y and Z                            | Extract class per responsibility    |
+| **O** Open/Closed           | Adding a feature requires modifying existing code   | Introduce strategy / plugin pattern |
+| **L** Liskov Substitution   | Subclass overrides parent method to throw           | Prefer composition over inheritance |
+| **I** Interface Segregation | Interface has methods most implementors don't need  | Split interface                     |
+| **D** Dependency Inversion  | High-level module imports concrete low-level module | Inject dependency via interface     |
+
+## Self-improving learnings
+
+`_learnings/refactor.yaml` records:
+
+- Preferred naming conventions for this project (camelCase, snake_case, etc.)
+- Established module boundaries (what belongs where)
+- Patterns the team uses (e.g. repository pattern, service layer)
+- Previous refactoring outcomes — what was improved and how
+
+## Integration
+
+- **agileflow-test-writer** — write or verify tests before any refactor begins; tests are the safety net that lets refactoring proceed without fear
+- **agileflow-audit** — use the audit skill to identify what needs refactoring; audit finds the code quality, duplication, and complexity issues, refactor fixes them
+- **agileflow-engineering** — when refactoring is part of a feature story, coordinate with engineering so the feature lands in already-cleaned code
+- **agileflow-pr-reviewer** — invoke after refactoring to confirm the changes preserved observable behaviour and meet style standards
+- **agileflow-performance** — when a refactor is performance-motivated (N+1 queries, blocking renders), pair with performance to measure before and after
+- **agileflow-debug** — if a refactor introduces a regression, hand off immediately to debug rather than reverting blindly
+- **agileflow-adr** — document significant refactoring decisions (module boundary changes, pattern migrations) as ADRs before executing them on large codebases
+- **agileflow-migration** — when a refactor involves a library upgrade or API migration alongside the structural cleanup, use migration to handle the version-specific steps
+
+## References
+
+| File                                 | When to load                                                               |
+| ------------------------------------ | -------------------------------------------------------------------------- |
+| `references/refactoring-patterns.md` | Detailed catalogue of refactoring patterns with before/after code examples |
+| `references/safety-checks.md`        | Pre/post refactoring safety checklist and risk assessment                  |
+
+## Workflows
+
+| File                          | When to follow                                                           |
+| ----------------------------- | ------------------------------------------------------------------------ |
+| `workflows/safe-refactor.md`  | Any refactoring task — assess safety, write tests, apply pattern, verify |
+| `workflows/extract-module.md` | Extracting a reusable module or function from a large file or class      |