@rubytech/create-maxy-code 0.1.169 → 0.1.170

package/payload/platform/plugins/venture-studio/skills/zero-to-prototype/references/research-synthesis.md

@@ -1,276 +0,0 @@
-# Research Synthesis
-
-## Purpose
-Combine qualitative research (interviews, usability tests, feedback) with quantitative data (analytics, metrics, surveys) to extract actionable insights that neither source could provide alone.
-
-## When to Use
-- Have both customer interview data AND product analytics
-- Need to understand WHY metrics are changing (not just WHAT)
-- Connecting user behavior patterns to stated motivations
-- Building a complete picture of the customer experience
-- Validating qualitative findings with quantitative data (or vice versa)
-
-## Core Principle
-
-**Quantitative data shows WHAT is happening.**
-**Qualitative data shows WHY it's happening.**
-**Synthesis connects the two.**
-
-Neither alone is sufficient:
-- Analytics without context leads to wrong conclusions
-- Interviews without data leads to anecdotes, not patterns
-
-## Process
-
-### 1. Organize Your Data Sources
-
-**Qualitative Sources:**
-| Source | What It Provides | Typical Location |
-|--------|------------------|------------------|
-| Customer interviews | Deep motivations, pain points, language | Transcripts, recordings |
-| Usability tests | Friction points, confusion moments | Session recordings, notes |
-| Support tickets | Real problems, customer language | Help desk system |
-| Sales call notes | Objections, buying triggers | CRM notes |
-| Social mentions | Unsolicited feedback, sentiment | Twitter, Reddit, forums |
-| Churn interviews | Why they left, what's missing | Exit surveys, calls |
-
-**Quantitative Sources:**
-| Source | What It Provides | Typical Location |
-|--------|------------------|------------------|
-| Product analytics | Usage patterns, funnels, retention | Mixpanel, Amplitude, PostHog |
-| Revenue metrics | Conversion, churn, expansion | Stripe, billing system |
-| Survey data | NPS, CSAT, feature requests | Typeform, SurveyMonkey |
-| A/B test results | What changes move metrics | Experiment platform |
-| Session recordings | Where users click, scroll, struggle | Hotjar, FullStory |
-| Cohort data | How behavior changes over time | Analytics platform |
-
-### 2. Five Synthesis Patterns
-
-#### Pattern 1: Revenue/Funnel Diagnostics
-
-**Question:** Why is [metric] declining?
-
-**Method:**
-1. Identify the WHAT from analytics (which metric, which segment, since when)
-2. Search qualitative data for the WHY (complaints, confusion, friction)
-3. Cross-reference timing (deployment logs, feature changes)
-4. Validate with additional data if needed
-
-**Example:**
-- **Quant:** Conversion dropped 15% starting March 1
-- **Context:** New pricing page deployed Feb 28
-- **Qual:** 3 support tickets mention "confusing pricing" in March
-- **Qual:** Usability test transcript: "I can't figure out which plan I need"
-- **Synthesis:** Pricing page redesign confused users → add comparison table
-
-#### Pattern 2: Funnel + Friction Mapping
-
-**Question:** Where do users drop and WHY?
-
-**Method:**
-1. Map the funnel stages with drop-off rates (analytics)
-2. Overlay qualitative friction mentions at each stage
-3. Identify stages with high drop + clear friction cause
-4. Prioritize fixes by (drop rate × addressability)
-
-**Synthesis Template:**
-
-| Stage | Drop Rate | Qual Friction | Mentions | Priority |
-|-------|-----------|---------------|----------|----------|
-| Signup → Onboarding | 40% | "Too many steps" | 5 | High |
-| Onboarding → Activation | 60% | "Didn't know what to do next" | 8 | Critical |
-| Activation → Week 2 | 30% | "Forgot about it" | 3 | Medium |
-
-#### Pattern 3: User Segmentation
-
-**Question:** Who are our power users and why?
-
-**Method:**
-1. Define behavioral hypothesis (what makes power users different?)
-2. Test against analytics (do they do X more than others?)
-3. Find power users and interview them (why do you do X?)
-4. Validate findings against broader cohort data
-
-**Example:**
-- **Hypothesis:** Power users connect integrations
-- **Test:** Users with 3+ integrations have 2x retention
-- **Interview:** "The integrations are what make it useful"
-- **Synthesis:** Integrations drive retention → optimize integration setup
-
-#### Pattern 4: Aha Moment Discovery
-
-**Question:** What drives long-term retention?
-
-**Method:**
-1. Mine interview data for "clicked" moments ("That's when I realized...")
-2. Translate to measurable behaviors
-3. Test retention correlation (do users who do X retain better?)
-4. Validate with cohort analysis
-
-**Example:**
-- **Qual:** "When I saw the agent reply to a customer, I knew I needed this"
-- **Behavior:** First AI-handled conversation
-- **Test:** Users who see AI conversation in day 1 retain 40% better
-- **Synthesis:** Aha moment = seeing AI work → optimize for day-1 conversation
-
-#### Pattern 5: Opportunity Validation
-
-**Question:** Is [feature request] real demand or noise?
-
-**Method:**
-1. Count unprompted mentions in qualitative data
-2. Check usage of related existing features
-3. Assess segment overlap (who asks for this?)
-4. Estimate impact (if we build this, what changes?)
-
-**Validation Matrix:**
-
-| Signal | Strong | Weak |
-|--------|--------|------|
-| Unprompted mentions | 5+ interviews | 1-2 mentions |
-| Support tickets | Recurring theme | One-off |
-| Workaround behavior | Users hacking around it | No workarounds |
-| Willingness to pay | "I'd pay more for this" | "Nice to have" |
-| Segment fit | Core users asking | Edge cases asking |
-
-### 3. Synthesis Framework
-
-**For each insight, document:**
-
-| Element | Description |
-|---------|-------------|
-| **Finding** | What we learned (one sentence) |
-| **Quant Evidence** | The numbers that show this |
-| **Qual Evidence** | The quotes/observations that explain it |
-| **Confidence** | High/Medium/Low based on evidence strength |
-| **Implication** | What this means for the product |
-| **Action** | Specific next step |
-
-**Example:**
-
-| Element | Detail |
-|---------|--------|
-| **Finding** | Users who see AI handle a conversation in day 1 retain 40% better |
-| **Quant** | Day-1 AI conversation cohort: 65% week-4 retention vs. 25% baseline |
-| **Qual** | Interview: "When I saw it actually reply to a customer, I knew I needed this" (×4 users) |
-| **Confidence** | High (strong correlation + consistent interview theme) |
-| **Implication** | First AI conversation is the activation moment |
-| **Action** | Redesign onboarding to guarantee AI conversation in session 1 |
-
-### 4. Common Pitfalls
-
-**Cherry-picking:**
-- Finding one quote to support a metric
-- Fix: Require multiple qual sources for each insight
-
-**False causation:**
-- Assuming correlation is causation
-- Fix: Look for mechanism (WHY would X cause Y?)
-
-**Recency bias:**
-- Overweighting recent interviews
-- Fix: Track themes over time
-
-**Loudest voice:**
-- One emphatic user shapes perception
-- Fix: Count mentions, don't just note them
-
-**Metric worship:**
-- Ignoring qual that contradicts quant
-- Fix: Investigate contradictions—they're often the insight
-
-### 5. Tools & Infrastructure
-
-**Qualitative Data Management:**
-- Tag interview transcripts by theme
-- Create searchable repository
-- Link quotes to customer profiles
-
-**Quantitative + Context:**
-- Document feature deployment dates
-- Note seasonality patterns
-- Maintain event/property definitions
-
-**Integration:**
-- Same customer ID across qual and quant
-- Ability to pull analytics for specific interview subjects
-- Combined dashboards showing both
-
-### 6. Synthesis Cadence
-
-| Frequency | Activity |
-|-----------|----------|
-| **Weekly** | Review new qual (tickets, interviews) against current metrics |
-| **Monthly** | Deep synthesis of a specific question |
-| **Quarterly** | Full customer journey synthesis |
-| **Ad-hoc** | When metrics change unexpectedly |
-
-### 7. Synthesis
-
-After completing research synthesis:
-- What do we know that we couldn't know from data OR interviews alone?
-- What contradictions remain unresolved?
-- What's the highest-confidence insight?
-- What would change our understanding if we learned it was wrong?
-- What's the next question to investigate?
-
-## Example
-
-**Context:** B2B SaaS product seeing declining trial-to-paid conversion
-
-### Data Collection
-
-**Quantitative:**
-- Trial-to-paid dropped from 12% to 8% over 3 months
-- Biggest drop in "team" trials (vs. individual)
-- Day-7 engagement down 20%
-- Pricing page bounce rate up 15%
-
-**Qualitative:**
-- 6 churn interviews: "Couldn't get my team to use it"
-- 4 support tickets: "How do I add team members?"
-- 2 sales calls: "Is there a team trial or do I need individual accounts?"
-- Usability test: User couldn't find "invite team" button (took 4 minutes)
-
-### Synthesis
-
-#### Finding 1: Team onboarding is broken
-
-| Element | Detail |
-|---------|--------|
-| **Finding** | Team trials fail because inviting teammates is hard |
-| **Quant** | Team trial conversion: 5% (down from 15%). Individual: 12% (unchanged). |
-| **Qual** | "Couldn't get my team to use it" (×6). "How do I add team members?" (×4). Usability test: 4 min to find invite. |
-| **Confidence** | High |
-| **Implication** | Team value requires team usage; if invites fail, value fails |
-| **Action** | Make "invite team" step 2 of onboarding (not buried in settings) |
-
-#### Finding 2: Pricing confusion for teams
-
-| Element | Detail |
-|---------|--------|
-| **Finding** | Team buyers confused about per-seat vs. team pricing |
-| **Quant** | Pricing page bounce +15%. Team segment most affected. |
-| **Qual** | "Is there a team trial?" (×2 sales calls). Usability: "I don't understand which plan is for my team." |
-| **Confidence** | Medium (fewer qual mentions) |
-| **Implication** | Pricing page loses team buyers before they try |
-| **Action** | Add team pricing toggle; clarify per-seat math |
-
-#### Finding 3: Aha moment is "team collaboration"
-
-| Element | Detail |
-|---------|--------|
-| **Finding** | Users who collaborate with teammate in week 1 convert 3x better |
-| **Quant** | Collab in week 1: 24% conversion. No collab: 8% conversion. |
-| **Qual** | "When my colleague replied in the app, I realized this could replace Slack threads" |
-| **Confidence** | High |
-| **Implication** | Aha moment for teams is seeing collaboration happen |
-| **Action** | Trigger first collaboration in onboarding (suggest inviting specific person) |
-
-### Prioritized Actions
-
-1. **Move "invite team" to onboarding step 2** (Finding 1 + 3: High confidence, high impact)
-2. **Add team pricing toggle with calculator** (Finding 2: Medium confidence, blocking conversion)
-3. **A/B test "invite specific colleague" prompt** (Finding 3: Test the hypothesis)
-
-**Insight:** Neither data source alone would have revealed that "invite team" being buried in settings was the root cause. Analytics showed team trials failing; interviews explained why. The synthesis turned a metric problem into a specific UX fix.

package/payload/platform/plugins/venture-studio/skills/zero-to-prototype/references/three-engines-of-growth.md

@@ -1,248 +0,0 @@
-# Three Engines of Growth
-
-## Purpose
-Identify and optimize the single growth engine that will drive sustainable growth for your business, avoiding the trap of trying to optimize everything at once.
-
-## When to Use
-- Deciding how to invest in growth
-- Choosing between competing growth strategies
-- Diagnosing why growth has stalled
-- Aligning team around growth metrics
-- Evaluating product-market fit progress
-
-## Process
-
-### 1. Understand the Three Engines
-
-Every sustainable business is powered by one primary engine:
-
-**1. Sticky Engine (Retention)**
-Growth from keeping customers longer
-- Key metric: Churn rate vs. acquisition rate
-- Formula: Growth = Acquisition Rate - Churn Rate
-- Focus: Engagement, habit formation, switching costs
-- Example: SaaS products, subscription services
-
-**2. Viral Engine (Word-of-Mouth)**
-Growth from customers bringing customers
-- Key metric: Viral coefficient (K)
-- Formula: If K > 1, exponential growth
-- Focus: Product quality, shareability, referral incentives
-- Example: Social networks, collaboration tools
-
-**3. Paid Engine (Advertising)**
-Growth from reinvesting revenue into acquisition
-- Key metric: LTV > CAC (with margin)
-- Formula: Marginal Profit = LTV - CAC
-- Focus: Conversion optimization, channel efficiency
-- Example: E-commerce, transactional services
-
-### 2. Identify Your Primary Engine
-
-**Which engine are you optimizing for?**
-
-Most companies can grow through multiple engines, but successful companies focus on ONE primary engine and optimize everything for it.
-
-**Diagnostic questions:**
-
-**For Sticky Engine:**
-- Do customers use your product daily/weekly?
-- Is there high switching cost?
-- Does value increase over time (data, network, customization)?
-- Is churn rate below 5% monthly?
-
-**For Viral Engine:**
-- Does using the product expose others to it?
-- Do users naturally share or invite others?
-- Is your viral coefficient approaching or exceeding 1?
-- Does the product improve with more users (network effects)?
-
-**For Paid Engine:**
-- Do you know your customer lifetime value?
-- Can you profitably acquire customers?
-- Is LTV > 3x CAC?
-- Are there scalable paid channels available?
-
-### 3. Optimize Your Engine
-
-**Sticky Engine Optimization:**
-
-| Metric | How to Improve |
-|--------|----------------|
-| Churn Rate | Better onboarding, engagement features, success programs |
-| Engagement | Daily use cases, notifications, habit loops |
-| Expansion Revenue | Upsells, add-ons, usage-based pricing |
-| NPS/CSAT | Product quality, support, proactive outreach |
-
-**Key Focus Areas:**
-- Onboarding experience (time-to-value)
-- Daily/weekly engagement hooks
-- Customer success and support
-- Feature adoption tracking
-- Cohort retention analysis
-
-**Viral Engine Optimization:**
-
-| Metric | How to Improve |
-|--------|----------------|
-| Viral Coefficient (K) | Invitation mechanics, sharing features, referral rewards |
-| Cycle Time | Faster onboarding, immediate value, easy invites |
-| Conversion from Invite | Better landing pages, social proof, incentives |
-| Network Effects | Features that improve with more users |
-
-**Key Focus Areas:**
-- Make sharing/inviting seamless
-- Create value that requires others (collaboration)
-- Referral programs with two-sided rewards
-- Social proof and public usage
-
-**Paid Engine Optimization:**
-
-| Metric | How to Improve |
-|--------|----------------|
-| LTV | Pricing, retention, upsells |
-| CAC | Ad creative, targeting, conversion rate |
-| LTV:CAC Ratio | Both of the above |
-| Payback Period | Faster time-to-value, annual prepay |
-
-**Key Focus Areas:**
-- Conversion rate optimization
-- Channel diversification
-- Pricing optimization
-- Customer segmentation (different LTV by segment)
-
-### 4. Measure Progress
-
-**Sticky Engine Metrics:**
-- Monthly churn rate (target: <5%)
-- Daily/Weekly Active Users (DAU/WAU)
-- Net Revenue Retention (target: >100%)
-- Feature adoption rates
-- NPS (target: >50)
-
-**Viral Engine Metrics:**
-- Viral coefficient (K)
-- Invitation rate (% of users who invite)
-- Invite conversion rate
-- Viral cycle time
-- Organic vs. paid user ratio
-
-**Paid Engine Metrics:**
-- Customer Acquisition Cost (CAC)
-- Customer Lifetime Value (LTV)
-- LTV:CAC ratio (target: >3:1)
-- Payback period (target: <12 months)
-- Return on Ad Spend (ROAS)
-
-### 5. Avoid Common Mistakes
-
-**Trying to optimize all three:**
-- Dilutes focus and resources
-- Different engines require different expertise
-- "Good at all three" usually means "great at none"
-
-**Wrong engine for your product:**
-- Not all products can be viral (B2B enterprise rarely is)
-- Not all products can be sticky (low-frequency use cases)
-- Not all products can be profitably acquired (low LTV)
-
-**Premature scaling:**
-- Scaling paid before LTV:CAC is proven
-- Pushing virality before product is ready
-- Focusing on acquisition before retention
-
-**Vanity metrics:**
-- Total signups instead of active users (sticky)
-- Invites sent instead of invites converted (viral)
-- Traffic instead of conversions (paid)
-
-### 6. Engine-Specific Product Decisions
-
-**If Sticky is your engine:**
-- Build features for daily use
-- Invest heavily in onboarding
-- Create switching costs (data, integrations, customization)
-- Build for one persona deeply, not many shallowly
-
-**If Viral is your engine:**
-- Make the product inherently social
-- Reduce friction to invite/share
-- Make inviting benefit the inviter, not just the invitee
-- Build for network effects
-
-**If Paid is your engine:**
-- Optimize conversion funnel obsessively
-- Experiment with pricing constantly
-- Build for high-intent purchase behavior
-- Create clear, measurable ROI for customers
-
-### 7. Synthesis
-
-After identifying your engine:
-- Is your product designed for this engine?
-- Are you measuring the right metrics?
-- Is your team focused on the right activities?
-- What would improve this engine's performance by 10%?
-- What engine-specific experiments should you run next?
-
-## Example
-
-**Product**: B2B sales intelligence platform
-
-### Engine Analysis
-
-**Could it be Sticky?**
-- Users need data daily for prospecting ✓
-- Data quality improves with use ✓
-- Integrations with CRM create switching cost ✓
-- High replacement cost ✓
-- **Assessment: Strong fit for Sticky**
-
-**Could it be Viral?**
-- Using it doesn't expose others to it ✗
-- Inviting others doesn't help the user ✗
-- No network effects ✗
-- **Assessment: Poor fit for Viral**
-
-**Could it be Paid?**
-- Clear ROI (more deals closed) ✓
-- High LTV ($10K+ annually) ✓
-- Identifiable buyer (Sales VP) ✓
-- **Assessment: Good fit for Paid**
-
-### Primary Engine Decision
-
-**Primary: Sticky Engine** (retention drives growth)
-**Secondary: Paid Engine** (initial acquisition)
-
-**Rationale:**
-- Viral doesn't work for this product type
-- Sticky is strong because daily use + high switching cost
-- Paid works as acquisition method, but retention is what compounds
-
-### Optimization Plan
-
-**Sticky Engine Focus:**
-1. **Onboarding:** Time-to-first-valuable-insight < 24 hours
-2. **Daily Use Hook:** Morning prospecting email with top leads
-3. **Data Accumulation:** Custom lists, notes, activity history
-4. **CRM Integration:** Deep Salesforce/HubSpot sync
-
-**Key Metrics:**
-- Daily Active Rate: 60% of paid users (target)
-- Monthly Churn: <3%
-- Net Revenue Retention: >110%
-
-**Paid Engine (Secondary):**
-- CAC Target: <$1,000
-- LTV Target: >$10,000
-- Channels: Google Ads, LinkedIn, SDR outreach
-
-### Results Framework
-
-**Month 1-3:** Establish baseline metrics
-**Month 4-6:** Run experiments on onboarding (time-to-value)
-**Month 7-9:** Test engagement hooks (daily email, mobile alerts)
-**Month 10-12:** Measure retention cohorts, adjust pricing
-
-**Insight:** By focusing on Sticky engine, every product decision is filtered through "does this increase daily use or retention?" This clarity prevents feature sprawl and keeps the team aligned on what matters.

package/payload/platform/plugins/venture-studio/skills/zero-to-prototype/references/validation-tests.md

@@ -1,89 +0,0 @@
-# Validation Tests
-
-## Purpose
-Define concrete, pass/fail test scenarios that prove a prototype works before going live. Validation tests are the bridge between "it's built" and "it's ready" — they catch workflow gaps, edge cases, and integration failures that desk-checking misses.
-
-## When to Use
-- After building a prototype, before the live validation sprint
-- When a PRD defines a multi-step workflow with cross-party coordination
-- When the prototype involves scheduled actions (cron, timeouts, follow-ups)
-- When there are gates/guards that must block incorrect states
-- Before declaring a sprint build "complete"
-
-## Process
-
-1. **Derive scenarios from the workflow**
-   - Walk through each step of the workflow and ask: "What proves this step works?"
-   - One test per step for the happy path
-   - Additional tests for every branch, timeout, and failure mode
-
-2. **Categorize by risk area**
-   - **Core workflow**: The happy path end-to-end. If this fails, nothing works.
-   - **Timeouts and expiry**: Scheduled actions that fire without human input. Easy to get wrong.
-   - **Escalation and enforcement**: Warning → penalty → removal progressions. Must fire in order.
-   - **Gates and guards**: Precondition checks that block invalid actions. Must be airtight.
-   - **Cross-session and scope**: Multi-party coordination where state is shared. Most technically fragile.
-   - **Information relay**: Passing data between parties while preserving constraints (e.g. anonymity).
-   - **Reputation and scoring**: Trust scores, priority tiers, blacklist thresholds. Must be deterministic.
-   - **Data compliance**: Access and erasure rights. Legal requirement — must work perfectly.
-   - **Scheduled job reliability**: Every cron/timeout type fires and the system acts on it correctly.
-
-3. **Write each test as a numbered scenario**
-   - **ID**: Short reference (T1, T2, ... Tn)
-   - **Title**: What it tests in plain English
-   - **Steps**: Numbered sequence of actions (input → expected behaviour)
-   - **Pass criteria**: What "success" looks like — specific state changes, messages sent, records updated
-   - Keep it concrete: use example values, names, amounts. Abstract tests are hard to run.
-
-4. **Order by dependency**
-   - Core workflow first (can't test edge cases if the happy path is broken)
-   - Gates and guards before escalation (guards prevent bad states that escalation handles)
-   - Cross-session before information relay (relay depends on scope resolution working)
-   - Data compliance last (depends on all other data being created correctly first)
-
-5. **Define the test environment**
-   - What test accounts/phones are needed?
-   - What seed data must exist before testing? (e.g. pre-created profiles, records)
-   - How are cron jobs accelerated for testing? (Shortened timers or manual trigger)
-   - How do you verify state after each step? (Check memory files, customer records, session history)
-
-6. **Run and record results**
-   - Run each test in order
-   - Record: pass/fail, actual behaviour, any deviations from expected
-   - If a test fails, fix the issue and re-run from the start of that test (not just the failing step)
-   - All tests must pass before declaring the build ready for live use
-
-## Test Count Guidelines
-
-| Prototype complexity | Typical test count |
-|---|---|
-| Simple (single-party, no scheduling) | 5–10 |
-| Moderate (multi-party OR scheduling) | 10–20 |
-| Complex (multi-party AND scheduling AND enforcement) | 20–30 |
-
-More tests are not necessarily better. Each test should cover a distinct scenario — if two tests would pass or fail together, merge them.
-
-## Example
-
-**Prototype**: AI booking agent that connects customers with service providers via WhatsApp.
-
-**Test categories and counts:**
-- Core workflow (happy path, extension round, both rounds fail): 3 tests
-- Quote expiry and timeouts (no response, 2nd expiry warning, 3rd expiry blacklist): 3 tests
-- Fee collection escalation (on time, late, full escalation to blacklist, reinstatement): 4 tests
-- Gates and guards (outstanding fee blocks booking, location filter, concurrent cap, opt-out, opt-in): 5 tests
-- Cross-session and scope (virtual group write access, access revocation, late response): 3 tests
-- Information relay (provider requests more info, photo forwarding, anonymity preserved): 1 test
-- Trust scores (shared during anonymous phase, hidden after reveal, score updates): 3 tests
-- Data compliance (export, deletion): 2 tests
-- Cron reliability (all scheduled job types fire correctly): 1 test
-
-**Total: 25 tests** — appropriate for a complex multi-party, scheduled, enforced workflow.
-
-## Common Pitfalls
-
-- **Testing only the happy path.** The happy path is the least likely to break. Timeouts, escalations, and edge cases are where prototypes fail.
-- **Not testing cron jobs end-to-end.** Scheduling a cron is easy; verifying the agent acts correctly when it fires is where bugs hide.
-- **Assuming cross-session state is visible.** If Party A writes data in their session, verify Party B can actually read it in theirs.
-- **Skipping gate tests.** A missing precondition check (e.g. outstanding payment) can let invalid state propagate through the entire workflow.
-- **Not re-running after fixes.** A fix to one test can break another. Re-run from the top of the category, not just the failing test.