@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/digital-marketing/references/revops-lifecycle.md

@@ -0,0 +1,170 @@
+# RevOps: Lead Lifecycle, Scoring & Routing
+
+> Reference for the digital-marketing skill. Revenue operations — the systems connecting marketing to sales.
+> Source: coreyhaines31/marketingskills (MIT) — adapted for Merlin ecosystem.
+
+## Core Principles
+
+**Single Source of Truth** — One CRM as the canonical source for every lead and account. If data lives in multiple places, it will conflict.
+
+**Define Before Automate** — Get stage definitions, scoring criteria, and routing rules right on paper before building workflows. Automating a broken process creates broken results faster.
+
+**Measure Every Handoff** — Every handoff between teams (Marketing→Sales, SDR→AE, AE→CS) is a potential leak. Each needs an SLA, a tracking mechanism, and someone accountable.
+
+**Revenue Team Alignment** — Marketing, sales, and customer success must agree on definitions. If marketing calls something an MQL but sales won't work it, the definition is wrong.
+
+---
+
+## Lead Lifecycle Framework
+
+### 7-Stage Lifecycle
+
+| Stage           | Entry Criteria                               | Exit Criteria                             | Owner             |
+| --------------- | -------------------------------------------- | ----------------------------------------- | ----------------- |
+| **Subscriber**  | Opts in to content (blog, newsletter)        | Provides company info or shows engagement | Marketing         |
+| **Lead**        | Identified contact with basic info           | Meets minimum fit criteria                | Marketing         |
+| **MQL**         | Passes fit + engagement threshold            | Sales accepts or rejects within SLA       | Marketing         |
+| **SQL**         | Sales accepts and qualifies via conversation | Opportunity created or recycled           | Sales (SDR/AE)    |
+| **Opportunity** | Budget, authority, need, timeline confirmed  | Closed-won or closed-lost                 | Sales (AE)        |
+| **Customer**    | Closed-won deal                              | Expands, renews, or churns                | CS / Account Mgmt |
+| **Evangelist**  | High NPS, referral activity, case study      | Ongoing program participation             | CS / Marketing    |
+
+### MQL Definition
+
+An MQL requires BOTH **fit** AND **engagement** — neither alone is sufficient:
+
+- **Fit** — Does this person match your ICP? (company size, industry, role, tech stack)
+- **Engagement** — Have they shown buying intent? (pricing page, demo request, multiple visits)
+
+Examples of what is NOT an MQL:
+
+- Perfect-fit company that never engages (no intent signal)
+- Student downloading every ebook (engagement without fit)
+- Bot-generated form fills (neither fit nor real engagement)
+
+### MQL-to-SQL Handoff SLA
+
+| Step              | Timeframe                           | Action                                                                        |
+| ----------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
+| MQL alert sent    | Immediate                           | Assigned rep notified with lead context                                       |
+| First contact     | Within **4 hours** (business hours) | Rep reaches out via phone/email                                               |
+| Qualify or reject | Within **48 hours**                 | Rep marks as SQL (accepted) or rejected with reason code                      |
+| Rejected MQLs     | Immediate                           | Returned to marketing nurture with reason (wrong fit, bad timing, competitor) |
+
+---
+
+## Lead Scoring
+
+### Three Scoring Dimensions
+
+**Explicit scoring (fit)** — Who they are:
+
+| Signal                    | Points (example) |
+| ------------------------- | ---------------- |
+| Target industry match     | +15              |
+| Company size 50-500       | +10              |
+| Director/VP/C-level title | +15              |
+| Target geography          | +5               |
+| Tech stack match          | +10              |
+
+**Implicit scoring (engagement)** — What they do:
+
+| Signal                   | Points (example) |
+| ------------------------ | ---------------- |
+| Pricing page visit       | +20              |
+| Demo request             | +30              |
+| Case study download      | +10              |
+| 3+ page visits in a week | +10              |
+| Webinar attendance       | +15              |
+| Email click              | +5               |
+| Product usage (PLG)      | +25              |
+
+**Negative scoring** — Disqualifying signals:
+
+| Signal                    | Points (example) |
+| ------------------------- | ---------------- |
+| Competitor email domain   | -50              |
+| Student/personal email    | -20              |
+| Unsubscribe               | -30              |
+| Job title: intern/student | -25              |
+| No activity in 90 days    | -15              |
+
+### Building a Scoring Model
+
+1. Define your ICP attributes and weight them by correlation to closed-won deals
+2. Identify high-intent behavioral signals from historical closed-won data
+3. Set point values for each attribute and behavior
+4. Set MQL threshold (typically **50-80 points** on a 100-point scale)
+5. Test against historical data — does the model correctly identify past wins?
+6. Launch, measure, and **recalibrate quarterly** (buyer behavior changes)
+
+### Common Scoring Mistakes
+
+- Weighting content downloads too heavily (research ≠ buying intent)
+- Not including negative scoring (lets bad leads through)
+- Setting and forgetting (recalibrate quarterly)
+- Scoring all page visits equally (pricing page ≠ blog post)
+- No decay on old engagement (a visit 6 months ago shouldn't count the same as yesterday)
+
+---
+
+## Lead Routing
+
+### Routing Methods
+
+| Method              | How It Works                                        | Best For                              |
+| ------------------- | --------------------------------------------------- | ------------------------------------- |
+| **Round-robin**     | Distribute evenly across reps                       | Equal territories, similar deal sizes |
+| **Territory-based** | Assign by geography, vertical, or segment           | Regional teams, industry specialists  |
+| **Account-based**   | Named accounts go to named reps                     | ABM motions, strategic accounts       |
+| **Skill-based**     | Route by deal complexity, product line, or language | Diverse product lines, global teams   |
+
+### Routing Rules
+
+- Route to the **most specific match** first, then fall back to general
+- Include a **fallback owner** — unassigned leads go cold fast
+- Round-robin should account for rep **capacity and availability** (PTO, quota attainment)
+- Log every routing decision for audit and optimization
+
+### Speed-to-Lead
+
+Response time is the single biggest factor in lead conversion:
+
+| Response Time        | Impact                     |
+| -------------------- | -------------------------- |
+| Within **5 minutes** | 21x more likely to qualify |
+| After **30 minutes** | Conversion drops by 10x    |
+| After **24 hours**   | Lead is effectively cold   |
+
+Build routing rules that prioritize speed. Alert reps immediately. Escalate if SLA is missed.
+
+---
+
+## RevOps Metrics
+
+| Metric             | Formula / Definition                                        | Benchmark          |
+| ------------------ | ----------------------------------------------------------- | ------------------ |
+| Lead-to-MQL rate   | MQLs / Total leads                                          | 5-15%              |
+| MQL-to-SQL rate    | SQLs / MQLs                                                 | 30-50%             |
+| SQL-to-Opportunity | Opportunities / SQLs                                        | 50-70%             |
+| Pipeline velocity  | (# deals × avg deal size × win rate) / avg sales cycle days | Varies by ACV      |
+| CAC                | Total sales + marketing spend / new customers               | —                  |
+| LTV:CAC ratio      | Customer lifetime value / CAC                               | 3:1 to 5:1 healthy |
+| Speed-to-lead      | Time from form fill to first rep contact                    | < 5 minutes ideal  |
+| Win rate           | Closed-won / total opportunities                            | 20-30% (varies)    |
+
+**Note:** For the LTV:CAC formula and audience funnel strategy, see also `references/traffic-management.md` which covers it from the paid traffic perspective.
+
+---
+
+## GTM Motion Context
+
+Before designing RevOps systems, understand the go-to-market motion:
+
+| Motion                | Characteristics                      | RevOps Focus                                                         |
+| --------------------- | ------------------------------------ | -------------------------------------------------------------------- |
+| **Product-Led (PLG)** | Free trial/freemium, self-serve      | Product usage scoring, PQL (Product Qualified Lead), in-app triggers |
+| **Sales-Led**         | Demo/call required, enterprise focus | MQL/SQL handoff, AE routing, pipeline stages                         |
+| **Hybrid**            | Free tier + sales for enterprise     | Both scoring models, segment-based routing                           |
+
+Adapt lifecycle stages, scoring, and routing to match your motion. PLG needs product engagement signals; Sales-Led needs meeting-based qualification.

package/.merlin-core/skills/domain/digital-marketing/references/revops-operations.md

@@ -0,0 +1,167 @@
+# RevOps: Pipeline, Automation & Data Operations
+
+> Reference for the digital-marketing skill. Pipeline management, CRM workflows, deal desk, and data hygiene.
+> Source: coreyhaines31/marketingskills (MIT) — adapted for Merlin ecosystem.
+
+## Pipeline Stage Management
+
+### 7 Pipeline Stages
+
+| Stage               | Required Fields                          | Exit Criteria                           |
+| ------------------- | ---------------------------------------- | --------------------------------------- |
+| **Qualified**       | Contact info, company, source, fit score | Discovery call scheduled                |
+| **Discovery**       | Pain points, current solution, timeline  | Needs confirmed, demo scheduled         |
+| **Demo/Evaluation** | Technical requirements, decision makers  | Positive evaluation, proposal requested |
+| **Proposal**        | Pricing, terms, stakeholder map          | Proposal delivered and reviewed         |
+| **Negotiation**     | Redlines, approval chain, close date     | Terms agreed, contract sent             |
+| **Closed Won**      | Signed contract, payment terms           | Handoff to CS complete                  |
+| **Closed Lost**     | Loss reason, competitor (if any)         | Post-mortem logged                      |
+
+### Stage Hygiene Rules
+
+- **Required fields per stage** — Don't let reps advance a deal without filling in required data
+- **Stale deal alerts** — Flag deals sitting in a stage beyond 2x the average time for that stage
+- **Stage skip detection** — Alert when deals jump stages (Qualified → Proposal skipping Discovery). This usually means the rep isn't qualifying properly.
+- **Close date discipline** — Push dates must include a reason. No silent pushes.
+
+### Pipeline Metrics
+
+| Metric                 | What It Tells You                                   |
+| ---------------------- | --------------------------------------------------- |
+| Stage conversion rates | Where deals die — find the biggest drop-off         |
+| Average time in stage  | Where deals stall — optimize the bottleneck         |
+| Pipeline velocity      | Revenue per day flowing through the funnel          |
+| Coverage ratio         | Pipeline value vs quota — target **3-4x** coverage  |
+| Win rate by source     | Which channels produce real revenue, not just leads |
+
+---
+
+## CRM Automation Workflows
+
+### Essential Automations
+
+| Trigger                   | Action                                      | Purpose                  |
+| ------------------------- | ------------------------------------------- | ------------------------ |
+| Lead meets MQL criteria   | Update lifecycle stage, notify assigned rep | Instant handoff          |
+| MQL assigned to rep       | Create follow-up task with deadline         | Ensure SLA is met        |
+| Rep misses SLA (4 hours)  | Notify manager, escalate                    | Prevent leads going cold |
+| Deal moves to Closed Won  | Notify CS, create onboarding task           | Smooth customer handoff  |
+| Deal moves to Closed Lost | Require loss reason, log post-mortem        | Learn from losses        |
+
+### Marketing-to-Sales Automations
+
+- **MQL alert** — Instant notification to assigned rep with full lead context (company, score, pages visited, content downloaded)
+- **Meeting booked** — Notify AE when prospect books via scheduling tool, auto-populate CRM with meeting details
+- **Lead activity digest** — Daily email summary of high-intent actions by active leads in rep's pipeline
+- **Re-engagement trigger** — Alert sales when a dormant lead (60+ days inactive) returns to the site
+
+### Calendar Scheduling Integration
+
+- **Round-robin scheduling** — Distribute meetings evenly across available team members
+- **Routing by criteria** — Enterprise leads → senior AEs, SMB → junior reps, inbound demo → assigned SDR
+- **Pre-meeting enrichment** — Auto-populate CRM record with enrichment data before the call
+- **No-show workflows** — Auto-send "sorry we missed you" email, reschedule link, notify rep to follow up
+
+---
+
+## Deal Desk Processes
+
+### When You Need a Deal Desk
+
+- ACV above **$25K** (or your threshold for non-standard deals)
+- Non-standard payment terms (net-90, quarterly billing)
+- Multi-year contracts with custom pricing
+- Volume discounts beyond published tiers
+- Custom legal terms or SLAs
+
+### Approval Workflow Tiers
+
+| Deal Size / Terms             | Approval Required |
+| ----------------------------- | ----------------- |
+| Standard pricing              | Auto-approved     |
+| 10-20% discount               | Sales manager     |
+| 20-40% discount               | VP Sales          |
+| 40%+ discount or custom terms | Deal desk review  |
+| Multi-year / enterprise       | Finance + Legal   |
+
+### Non-Standard Terms Tracking
+
+Document every exception. Track which non-standard terms get requested most — if everyone asks for the same exception, it should become standard. Review quarterly and update pricing/terms accordingly.
+
+---
+
+## Data Hygiene & Enrichment
+
+### Dedup Strategy
+
+| Element        | Rule                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| Match keys     | Email domain + company name + phone (primary), full name + company (secondary)              |
+| Merge priority | CRM record wins over marketing automation; most recent activity wins for conflicting fields |
+| Cadence        | Weekly automated dedup with manual review for edge cases                                    |
+
+### Required Fields Enforcement
+
+- Enforce required fields at each lifecycle stage transition
+- Block stage advancement if critical fields are empty
+- Use **progressive profiling** — don't require everything upfront. Gather more data as leads engage deeper.
+
+### Enrichment Tools
+
+| Tool         | Strength                                       | Best For                |
+| ------------ | ---------------------------------------------- | ----------------------- |
+| **Clearbit** | Real-time enrichment, accurate tech stack data | Tech companies, PLG     |
+| **Apollo**   | Contact data + outbound sequences              | Prospecting-heavy teams |
+| **ZoomInfo** | Largest B2B database, enterprise-grade         | Enterprise sales orgs   |
+
+### Quarterly Audit Checklist
+
+- [ ] Review and merge duplicate records
+- [ ] Validate email deliverability on contacts inactive 6+ months
+- [ ] Archive contacts with no activity in 12+ months
+- [ ] Audit lifecycle stage distribution — look for bottlenecks (too many MQLs not converting = scoring problem)
+- [ ] Verify enrichment data accuracy on a random sample (50-100 records)
+
+---
+
+## RevOps Dashboard Structure
+
+Build three views for different stakeholders:
+
+### Marketing View
+
+- Lead volume (total, by source, by campaign)
+- MQL rate and MQL volume trend
+- Source attribution (which channels drive MQLs)
+- Cost per MQL by channel
+- Content attribution (which content drives conversions)
+
+### Sales View
+
+- Pipeline value (total and by stage)
+- Stage conversion rates (weekly trend)
+- Pipeline velocity (deals × value × win rate / cycle days)
+- Forecast accuracy (predicted vs actual close)
+- Rep performance (meetings booked, SQLs, win rate)
+
+### Executive View
+
+- CAC and LTV:CAC ratio (monthly trend)
+- Revenue vs target (actual, committed, upside)
+- Pipeline coverage ratio (target: 3-4x quota)
+- Channel efficiency (CAC by acquisition channel)
+- Expansion revenue and churn rate
+
+---
+
+## RevOps Output Format
+
+When delivering RevOps recommendations, provide:
+
+1. **Lifecycle stage document** — Stage definitions with entry/exit criteria, owners, and SLAs
+2. **Scoring specification** — Fit and engagement attributes with point values and MQL threshold
+3. **Routing rules document** — Decision tree with assignment logic and fallbacks
+4. **Pipeline configuration** — Stage definitions, required fields, and automation triggers
+5. **Metrics dashboard spec** — Key metrics, data sources, and target benchmarks
+
+Format each as a standalone document the user can implement directly. Include platform-specific guidance when the CRM is known (HubSpot, Salesforce, Pipedrive, etc.).

package/.merlin-core/skills/domain/digital-marketing/references/schema-markup.md

@@ -0,0 +1,190 @@
+# Schema Markup & Structured Data Reference
+
+> Reference for the digital-marketing skill. JSON-LD schema markup for rich results in search.
+> Source: coreyhaines31/marketingskills (MIT) — adapted for Merlin ecosystem.
+
+**Cross-reference:** For programmatic SEO pages that need schema at scale, see `references/programmatic-seo.md`.
+
+## Core Principles
+
+- **Accuracy first** — Schema must accurately represent page content. Don't mark up content that doesn't exist.
+- **Use JSON-LD** — Google's recommended format. Easier to implement and maintain than Microdata or RDFa.
+- **Follow Google guidelines** — Only use markup Google supports. Avoid spam tactics.
+- **Validate everything** — Test before deploying. Monitor Search Console. Fix errors promptly.
+
+## Common Schema Types
+
+| Type                    | Use For                   | Required Properties                        | Rich Result          |
+| ----------------------- | ------------------------- | ------------------------------------------ | -------------------- |
+| **Organization**        | Company homepage/about    | name, url                                  | Knowledge panel      |
+| **WebSite**             | Homepage                  | name, url                                  | Sitelinks search box |
+| **Article**             | Blog posts, news          | headline, image, datePublished, author     | Article cards        |
+| **Product**             | Product pages             | name, image, offers (price + availability) | Product cards, price |
+| **SoftwareApplication** | SaaS/app pages            | name, offers                               | App cards            |
+| **FAQPage**             | FAQ content               | mainEntity (Q&A array)                     | FAQ accordion        |
+| **HowTo**               | Tutorials, guides         | name, step                                 | How-to steps         |
+| **BreadcrumbList**      | Any page with breadcrumbs | itemListElement                            | Breadcrumb trail     |
+| **LocalBusiness**       | Local business pages      | name, address                              | Local pack, map      |
+| **Event**               | Events, webinars          | name, startDate, location                  | Event cards          |
+
+## JSON-LD Implementation
+
+Place in `<head>` or at the end of `<body>`:
+
+### Organization
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Your Company",
+  "url": "https://yoursite.com",
+  "logo": "https://yoursite.com/logo.png",
+  "sameAs": [
+    "https://twitter.com/yourcompany",
+    "https://linkedin.com/company/yourcompany"
+  ],
+  "contactPoint": {
+    "@type": "ContactPoint",
+    "email": "support@yoursite.com",
+    "contactType": "customer support"
+  }
+}
+```
+
+### Article / BlogPosting
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Article Title",
+  "image": "https://yoursite.com/image.jpg",
+  "datePublished": "2026-01-15",
+  "dateModified": "2026-03-10",
+  "author": {
+    "@type": "Person",
+    "name": "Author Name",
+    "url": "https://yoursite.com/about"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Your Company",
+    "logo": { "@type": "ImageObject", "url": "https://yoursite.com/logo.png" }
+  },
+  "description": "Brief description of the article content."
+}
+```
+
+### Product
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "image": "https://yoursite.com/product.jpg",
+  "description": "Product description",
+  "brand": { "@type": "Brand", "name": "Your Brand" },
+  "offers": {
+    "@type": "Offer",
+    "price": "49.00",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock",
+    "url": "https://yoursite.com/product"
+  },
+  "aggregateRating": {
+    "@type": "AggregateRating",
+    "ratingValue": "4.5",
+    "reviewCount": "127"
+  }
+}
+```
+
+### FAQPage
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is your return policy?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "We offer a 30-day money-back guarantee on all plans."
+      }
+    },
+    {
+      "@type": "Question",
+      "name": "Do you offer a free trial?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "Yes, all plans include a 14-day free trial. No credit card required."
+      }
+    }
+  ]
+}
+```
+
+### BreadcrumbList
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://yoursite.com"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "Blog",
+      "item": "https://yoursite.com/blog"
+    },
+    { "@type": "ListItem", "position": 3, "name": "Article Title" }
+  ]
+}
+```
+
+## Validation
+
+### Tools
+
+- **Google Rich Results Test** — `https://search.google.com/test/rich-results` — validates specific URLs
+- **Schema Markup Validator** — `https://validator.schema.org/` — validates raw JSON-LD
+- **Google Search Console** — monitor rich result status and errors at scale
+
+### Validation Process
+
+1. Write JSON-LD for the page
+2. Test with Rich Results Test (check for errors AND warnings)
+3. Deploy to page
+4. Monitor Search Console for indexing and errors
+5. Fix errors within 48 hours (Google recrawls quickly)
+
+## Common Mistakes
+
+| Mistake                                          | Impact                    | Fix                            |
+| ------------------------------------------------ | ------------------------- | ------------------------------ |
+| Marking up content that doesn't exist on page    | Manual action / penalty   | Only mark up visible content   |
+| Missing required properties                      | Rich result won't show    | Check required fields per type |
+| Incorrect nesting (e.g., Review outside Product) | Validation error          | Follow schema.org hierarchy    |
+| Stale data (price changed, event passed)         | Misleading search results | Automate schema from CMS data  |
+| Duplicate schema types on same page              | Confuses crawlers         | One primary type per page      |
+| Using Microdata instead of JSON-LD               | Harder to maintain        | Convert to JSON-LD             |
+
+## SEO Fields Checklist (Per Page Type)
+
+Every page with schema should also have:
+
+- [ ] Unique `<title>` tag (50-60 chars)
+- [ ] Unique meta description (120-160 chars)
+- [ ] Open Graph image (1200x630px)
+- [ ] Canonical URL (`<link rel="canonical">`)
+- [ ] Appropriate robots directive (index/noindex)