@veyralabs/skills 0.4.1 → 0.5.1

package/skills/venture-suite/venture-analyst/references/traction.md

@@ -0,0 +1,154 @@
+# Traction Reference
+
+Gabriel Weinberg & Justin Mares, "Traction" (2014).
+Framework for finding customer acquisition channels that actually work.
+
+## Core insight
+
+Most startups fail not because of product problems but traction problems. Building product and finding traction should happen in parallel, not sequentially.
+
+Half your time should be spent on traction, not product — even pre-launch.
+
+## The 19 traction channels
+
+1. **Viral marketing** - product spreads through existing users (Dropbox, Slack)
+2. **PR** - traditional press coverage
+3. **Unconventional PR** - stunts, giveaways, memorable campaigns
+4. **Search engine marketing (SEM)** - paid search (Google Ads)
+5. **Social and display ads** - Meta, LinkedIn, programmatic
+6. **Offline ads** - billboards, radio, TV, print
+7. **Search engine optimization (SEO)** - organic search
+8. **Content marketing** - blog, YouTube, podcast as acquisition
+9. **Email marketing** - list building and outbound sequences
+10. **Engineering as marketing** - free tools, calculators, embeds that drive signups
+11. **Targeting blogs** - get covered by influential niche blogs
+12. **Business development** - partnerships with complementary products
+13. **Sales** - direct outbound sales, inside sales teams
+14. **Affiliate programs** - revenue share for referrals
+15. **Existing platforms** - App Store, Shopify App Store, Chrome extensions, marketplace distribution
+16. **Trade shows** - industry events, conferences
+17. **Offline events** - meetups, workshops, demos
+18. **Speaking engagements** - conferences, podcasts, webinars
+19. **Community building** - Slack groups, forums, ambassador programs
+
+## Bullseye Framework
+
+Don't try all 19 channels. Use the Bullseye to find the one that works.
+
+### Step 1 — Brainstorm (outer ring)
+For each of the 19 channels, answer:
+- How could we use this channel?
+- What would success look like?
+- How could we test it cheaply?
+
+Produces 19 rough hypotheses.
+
+### Step 2 — Rank (middle ring)
+Score each channel on 3 criteria (1-3):
+- Probability of working
+- Volume potential (enough customers to matter)
+- Cost per acquisition (time + money)
+
+Pick the top 6 channels. These are your "promising" channels.
+
+### Step 3 — Test (inner ring — the bullseye)
+Pick the 3 channels with highest combined score. Run cheap, fast tests on each simultaneously.
+
+Each test:
+- Fixed budget (~€200-500)
+- Fixed time (2-4 weeks)
+- One metric: cost per lead, or signups, or revenue
+
+### Step 4 — Focus
+One test will outperform the others. Focus 100% on that channel. Optimize it until it no longer scales.
+
+When the channel plateaus, go back to Step 2.
+
+## Channel selection by stage
+
+Different channels dominate at different stages:
+
+| Stage | Best channels |
+|-------|--------------|
+| Pre-PMF | Direct sales, outreach, niche blogs, communities |
+| Early growth | Content, SEO, partnerships, email |
+| Scaling | Paid acquisition (once LTV:CAC proven), viral, affiliates |
+| Dominant | Brand, PR, events |
+
+**Pre-PMF rule:** channels that require scale to work (SEO, paid ads, viral) are wrong for early stage. You don't have enough data to optimize them. Use channels where you control the targeting.
+
+## Channel-market fit
+
+Some channels only work for specific markets:
+
+| Channel | Works for |
+|---------|-----------|
+| Cold outbound | B2B with clear ICP, high LTV |
+| Content/SEO | Markets that Google actively |
+| Product-led viral | Consumer, collaboration tools |
+| Community | Niche markets with strong identity |
+| Paid social | B2C with wide audience |
+| Trade shows | B2B with offline buying decisions |
+| Partnerships | Products with complementary distribution |
+
+Picking the wrong channel for your market wastes 6 months.
+
+## Cost benchmarks (rough, 2024)
+
+| Channel | Metric | B2C benchmark | B2B benchmark |
+|---------|--------|--------------|--------------|
+| Facebook/Instagram ads | CPL | €3-8 | €15-30 |
+| Google Search | CPL | €5-15 | €20-60 |
+| LinkedIn ads | CPL | - | €40-100 |
+| Cold email | CPL | - | €20-80 (time cost) |
+| Content/SEO | CPL | €5-20 (long term) | €15-50 (long term) |
+| Referral/viral | CPL | €1-5 | €5-20 |
+
+LTV must be at least 3x CAC for paid channels to be viable.
+
+## Traction metrics by channel
+
+**Viral / product-led:**
+- K-factor = (invites per user) × (invite conversion rate). Target K > 0.5 for meaningful viral effect
+- Time to viral loop: how fast does one user create another?
+
+**Content / SEO:**
+- Organic sessions per month
+- Keyword rankings for high-intent terms
+- Time to rank: SEO takes 3-6 months minimum to show results
+
+**Email:**
+- List growth rate per week
+- Open rate: >30% is good for cold; >50% for warm
+- Click-through: >5% is strong
+
+**Paid acquisition:**
+- CPL and CAC (cost per acquired customer)
+- Payback period: how many months to recoup CAC?
+- ROAS (return on ad spend)
+
+**Sales:**
+- Leads per week
+- Conversion rate (leads to paying)
+- Sales cycle length
+- Average contract value
+
+## Applying to venture analysis
+
+In Phase 3 (validation), recommend channels based on:
+
+1. Market type (B2B vs B2C)
+2. LTV estimate (high LTV = more channels viable)
+3. Available budget
+4. Target customer location (online? offline? specific communities?)
+
+For zero-budget startups, the viable channels are:
+- Direct outreach (cold email/DM) — time only
+- Niche community posting (Reddit, specific Slack/Discord groups) — time only
+- Engineering as marketing — build a free tool that attracts ICPs
+- Content on a specific topic ICP searches for
+
+For startups with €100-500/month budget:
+- Fake door test (landing page + small paid traffic)
+- LinkedIn outreach with Sales Navigator trial
+- Sponsored newsletter in a niche (often €100-300 per send)

package/skills/venture-suite/venture-analyst/scripts/enhance_detect.py

@@ -0,0 +1,172 @@
+"""
+Level 2 auto-detection.
+Silently detects available enhancements. Never asks the user for config.
+"""
+import os
+import subprocess
+import time
+import requests
+
+
+def detect_level() -> dict:
+    """
+    Detect what's available. Returns a capability map.
+    Called once at session start — results cached for the session.
+    """
+    return {
+        "docker":          _has_docker(),
+        "searxng":         _has_searxng(),
+        "veyrascrape_mcp": _has_env("VEYRASCRAPE_API_KEY"),
+        "github_token":    _has_env("GITHUB_TOKEN"),
+        "exa_key":         _has_env("EXA_API_KEY"),
+        "tavily_key":      _has_env("TAVILY_API_KEY"),
+        "groq_key":        _has_env("GROQ_API_KEY"),
+    }
+
+
+def _has_env(key: str) -> bool:
+    val = os.environ.get(key, "").strip()
+    return bool(val)
+
+
+def _has_docker() -> bool:
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=4,
+        )
+        return result.returncode == 0
+    except Exception:
+        return False
+
+
+def _has_searxng(ports: list[int] = None) -> bool:
+    if ports is None:
+        ports = [8080, 8888, 4000]
+    for port in ports:
+        try:
+            r = requests.get(
+                f"http://localhost:{port}/search",
+                params={"q": "test", "format": "json"},
+                timeout=2,
+            )
+            if r.status_code == 200:
+                return True
+        except Exception:
+            pass
+    return False
+
+
+def ensure_searxng() -> dict:
+    """
+    Launch SearXNG via Docker if available and not already running.
+    Returns status dict.
+    """
+    if _has_searxng():
+        return {"available": True, "url": "http://localhost:8080", "launched": False}
+
+    if not _has_docker():
+        return {"available": False, "reason": "docker_not_found"}
+
+    try:
+        subprocess.run(
+            [
+                "docker", "run", "-d",
+                "--name", "venture-searxng",
+                "-p", "8080:8080",
+                "searxng/searxng",
+            ],
+            capture_output=True,
+            timeout=45,
+        )
+        # give it time to start
+        for _ in range(6):
+            time.sleep(2)
+            if _has_searxng():
+                return {"available": True, "url": "http://localhost:8080", "launched": True}
+        return {"available": False, "reason": "searxng_start_timeout"}
+    except Exception as e:
+        return {"available": False, "reason": str(e)}
+
+
+def search_searxng(query: str, url: str = "http://localhost:8080", limit: int = 10) -> list[dict]:
+    """Search via local SearXNG instance."""
+    try:
+        r = requests.get(
+            f"{url}/search",
+            params={"q": query, "format": "json", "pageno": 1},
+            timeout=10,
+        )
+        results = r.json().get("results", [])[:limit]
+        return [
+            {
+                "source": "searxng",
+                "title": res.get("title", ""),
+                "url": res.get("url", ""),
+                "text": res.get("content", ""),
+                "engine": res.get("engine", ""),
+            }
+            for res in results
+        ]
+    except Exception:
+        return []
+
+
+def search_with_exa(query: str, api_key: str, limit: int = 10) -> list[dict]:
+    """Semantic search via Exa API (optional Level 3 enhancement)."""
+    try:
+        import exa_py
+        exa = exa_py.Exa(api_key=api_key)
+        results = exa.search(query, num_results=limit, use_autoprompt=True)
+        return [
+            {
+                "source": "exa",
+                "title": r.title or "",
+                "url": r.url,
+                "text": r.text or "",
+            }
+            for r in results.results
+        ]
+    except Exception:
+        return []
+
+
+def best_search(query: str, env: dict, limit: int = 10) -> list[dict]:
+    """
+    Use the best available search method based on detected environment.
+    Priority: Exa > SearXNG > Tavily > ddgs
+    """
+    # Level 3: Exa
+    if env.get("exa_key"):
+        results = search_with_exa(query, os.environ["EXA_API_KEY"], limit)
+        if results:
+            return results
+
+    # Level 2: SearXNG
+    if env.get("searxng"):
+        results = search_searxng(query, limit=limit)
+        if results:
+            return results
+
+    # Level 2: Tavily
+    if env.get("tavily_key"):
+        try:
+            from tavily import TavilyClient
+            client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
+            response = client.search(query, max_results=limit)
+            return [
+                {
+                    "source": "tavily",
+                    "title": r.get("title", ""),
+                    "url": r.get("url", ""),
+                    "text": r.get("content", ""),
+                }
+                for r in response.get("results", [])
+            ]
+        except Exception:
+            pass
+
+    # Level 1: ddgs (always available)
+    from scripts.sources import search_web
+    return search_web(query, limit)

package/skills/venture-suite/venture-analyst/scripts/experiments.py

@@ -0,0 +1,228 @@
+"""
+Validation experiment generator.
+Based on Lean Startup + Mom Test methodology.
+Outputs concrete, actionable experiments — not analysis.
+"""
+
+EXPERIMENTS = {
+    "cold_outreach": {
+        "name": "Cold Outreach Test",
+        "type": "discovery",
+        "cost": "0€",
+        "duration": "5-7 days",
+        "effort": "medium",
+        "goal": "Validate problem exists and find early adopters",
+        "process": [
+            "Identify 50 potential customers on LinkedIn, Reddit, or niche communities",
+            "Send short message: 'I'm researching [problem area] — would you spare 15 min?'",
+            "Do NOT pitch. Ask about their current process and pain.",
+            "Apply Mom Test: ask about past behavior, not future intentions",
+        ],
+        "metric": "Response rate + calls booked",
+        "success_criteria": "≥10% response rate, ≥3 discovery calls completed",
+        "red_flags": [
+            "Everyone says 'great idea' but nobody wants a call",
+            "People say they'd pay but won't commit to a free beta",
+            "You have to explain the problem before they understand it",
+        ],
+        "mom_test_questions": [
+            "Tell me how you currently handle [problem]. Walk me through your last time.",
+            "What's the most frustrating part of that process?",
+            "Have you tried other solutions? What happened?",
+            "How much time/money does this cost you per month right now?",
+            "What would you do if this problem disappeared tomorrow?",
+        ],
+        "bad_questions_to_avoid": [
+            "Would you use a tool that does X?",
+            "Do you think this is a good idea?",
+            "Would you pay $X for this?",
+            "How much would you pay for this?",
+        ],
+    },
+
+    "fake_door": {
+        "name": "Fake Door Test",
+        "type": "demand_signal",
+        "cost": "0-30€",
+        "duration": "7-14 days",
+        "effort": "low",
+        "goal": "Measure real demand before building anything",
+        "process": [
+            "Build a landing page (Carrd.co free, 30 min)",
+            "Describe the value proposition clearly — no features, only outcome",
+            "Add a CTA button: 'Join Waitlist' or 'Get Early Access'",
+            "When clicked: show 'Thanks, we'll notify you' — collect email",
+            "Drive traffic: 2-3 Reddit posts in relevant communities + LinkedIn",
+            "Track: page visits, CTA clicks, emails collected",
+        ],
+        "metric": "CTA click-through rate (CTR)",
+        "success_criteria": "≥5% CTR from cold traffic, ≥50 emails in 14 days",
+        "tools": [
+            "Carrd.co — free landing pages",
+            "Tally.so — free forms with email collection",
+            "Google Analytics (free) — traffic tracking",
+            "Plausible.io — privacy-friendly alternative",
+        ],
+        "headline_formula": "[Outcome they want] without [current pain]",
+        "subheadline_formula": "[Product name] helps [target customer] [achieve outcome] by [key mechanism]",
+        "red_flags": [
+            "CTR below 2% consistently",
+            "High visits but nobody clicks CTA",
+            "Traffic only from your own network — zero cold traffic",
+        ],
+    },
+
+    "waitlist": {
+        "name": "Waitlist Campaign",
+        "type": "demand_signal",
+        "cost": "0€",
+        "duration": "14-30 days",
+        "effort": "medium",
+        "goal": "Build an audience before building the product",
+        "process": [
+            "Build landing with value proposition + email signup",
+            "Write 3-5 posts for relevant communities (Reddit, LinkedIn, Twitter)",
+            "Frame as 'I'm building X because Y — who's interested?'",
+            "Respond to every comment — this is customer research",
+            "Track: emails per day, most common questions, what resonates",
+        ],
+        "metric": "Email signups per week",
+        "success_criteria": "100 organic signups in 30 days without paid ads",
+        "tools": [
+            "Beehiiv (free for <2500 subs) — email list",
+            "Carrd.co — landing",
+            "Reddit (organic, zero cost)",
+            "LinkedIn (organic, zero cost)",
+        ],
+        "red_flags": [
+            "Only your friends/connections sign up",
+            "High unsubscribe rate on first email",
+            "Nobody shares it organically",
+        ],
+    },
+
+    "concierge_mvp": {
+        "name": "Concierge MVP",
+        "type": "value_validation",
+        "cost": "0€",
+        "duration": "2-4 weeks",
+        "effort": "high",
+        "goal": "Deliver the core value manually to 3-5 real users",
+        "process": [
+            "Find 3-5 people with the problem (from outreach or waitlist)",
+            "Offer to do the service manually for free",
+            "Do it by hand: spreadsheets, email, calls, manual research",
+            "Observe where they get value, where they get frustrated",
+            "At the end: 'Would you pay X/month for this if it was automated?'",
+        ],
+        "metric": "Willingness to pay (real commitment, not hypothetical)",
+        "success_criteria": "≥3/5 users say yes to paying target price, 1+ pre-orders",
+        "key_question": "If this service disappeared tomorrow, what would you do?",
+        "what_to_track": [
+            "Which parts of the manual process they value most",
+            "Which parts they don't care about",
+            "How often they'd use it",
+            "What would make them stop using it",
+            "Who else they'd recommend it to",
+        ],
+        "red_flags": [
+            "'I'd use it but can't commit right now'",
+            "They use it but never refer anyone",
+            "The manual process takes so long it's not viable to automate",
+        ],
+    },
+
+    "smoke_test_ads": {
+        "name": "Paid Smoke Test",
+        "type": "demand_signal",
+        "cost": "30-100€",
+        "duration": "7 days",
+        "effort": "medium",
+        "goal": "Measure demand with cold paid traffic — no bias from network",
+        "process": [
+            "Set up landing page with single CTA",
+            "Run €30-50 in Meta or Google Ads to target audience",
+            "B2C: Facebook/Instagram interest targeting",
+            "B2B: LinkedIn job title targeting (more expensive, ~€5-10/click)",
+            "Measure CPL (cost per lead) — this is your true demand signal",
+        ],
+        "metric": "Cost Per Lead (CPL)",
+        "success_criteria": "B2C CPL < 5€, B2B CPL < 40€",
+        "tools": [
+            "Meta Ads Manager (€30 minimum budget)",
+            "Google Ads (€10/day minimum)",
+            "LinkedIn Ads (most expensive — B2B only, €15-50/click)",
+        ],
+        "red_flags": [
+            "CPL 5x higher than benchmark — market doesn't respond to messaging",
+            "Clicks but no conversions — landing page or offer problem",
+            "Can't target audience precisely — unclear ICP",
+        ],
+    },
+}
+
+
+def generate_experiments(
+    idea: str,
+    target_customer: str,
+    market_type: str = "b2c",
+    competition_level: str = "medium",
+    budget: str = "zero",
+) -> list[dict]:
+    """
+    Generate 3 prioritized validation experiments.
+    Always starts with the cheapest, highest-signal experiments first.
+    """
+    selected = []
+
+    # Always: Cold outreach first (zero cost, real signal)
+    exp = EXPERIMENTS["cold_outreach"].copy()
+    exp["priority"] = 1
+    exp["customized_for"] = idea
+    exp["target"] = target_customer
+    selected.append(exp)
+
+    # Always: Fake door (low cost, measurable)
+    exp = EXPERIMENTS["fake_door"].copy()
+    exp["priority"] = 2
+    exp["customized_for"] = idea
+    selected.append(exp)
+
+    # B2B with budget: concierge MVP
+    # B2C with budget: waitlist
+    if market_type.lower() == "b2b" or competition_level == "high":
+        exp = EXPERIMENTS["concierge_mvp"].copy()
+        exp["priority"] = 3
+        exp["customized_for"] = idea
+        exp["target"] = target_customer
+        selected.append(exp)
+    else:
+        exp = EXPERIMENTS["waitlist"].copy()
+        exp["priority"] = 3
+        exp["customized_for"] = idea
+        selected.append(exp)
+
+    return selected
+
+
+def format_experiment_output(experiments: list[dict], idea: str) -> str:
+    """Format experiments as markdown output."""
+    lines = [f"# Validation Experiments — {idea}\n"]
+    lines.append("Start with Experiment 1. Only move to the next if the previous fails.\n")
+
+    for exp in experiments:
+        lines.append(f"## Experiment {exp['priority']}: {exp['name']}")
+        lines.append(f"**Cost:** {exp['cost']} | **Duration:** {exp['duration']} | **Effort:** {exp['effort']}")
+        lines.append(f"\n**Goal:** {exp['goal']}\n")
+        lines.append("**Process:**")
+        for step in exp.get("process", []):
+            lines.append(f"- {step}")
+        lines.append(f"\n**Metric:** {exp['metric']}")
+        lines.append(f"**Success:** {exp['success_criteria']}")
+        if exp.get("red_flags"):
+            lines.append("\n**Red flags to watch:**")
+            for flag in exp["red_flags"]:
+                lines.append(f"- {flag}")
+        lines.append("")
+
+    return "\n".join(lines)