claude-plugin-wordpress-manager 2.2.0 → 2.3.0

package/skills/wp-content-attribution/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: wp-content-attribution
+description: |
+  This skill should be used when the user asks to "track content ROI",
+  "attribute sales to content", "measure content performance", "conversion tracking",
+  "UTM tracking setup", "which content drives sales", "content attribution",
+  "revenue per post", "customer acquisition source", "marketing attribution",
+  or mentions connecting WordPress content metrics with WooCommerce sales data.
+version: 1.0.0
+---
+
+## Overview
+
+Content-Commerce Attribution measures which WordPress content pieces drive WooCommerce conversions, enabling data-driven content strategy. By linking UTM-tracked traffic to order data, you can calculate ROI per content piece — answering "which blog posts actually generate revenue?"
+
+This skill orchestrates existing MCP tools — WooCommerce reports, content CRUD, order management — into attribution workflows. No new tools or custom plugins are required; UTM capture uses lightweight mu-plugin patterns.
+
+## When to Use
+
+- User has a WooCommerce store plus blog/content and wants to understand content ROI
+- "Which of my blog posts are driving the most sales?"
+- "How do I track which content leads to purchases?"
+- "Set up UTM tracking for my WooCommerce store"
+- "Calculate revenue per blog post"
+- "Build a content attribution dashboard"
+- "What's my customer acquisition cost by content type?"
+
+## Attribution vs Analytics
+
+| Aspect | Attribution | Analytics |
+|--------|------------|-----------|
+| Measures | Contribution to conversion | Traffic and engagement |
+| Answer | "This post generated $5,000 in revenue" | "This post got 10,000 visits" |
+| Data source | Order meta + UTM params | Page views + sessions |
+| Granularity | Revenue per content piece | Visitors per content piece |
+| Action | Invest more in high-ROI content | Invest in high-traffic topics |
+
+## Prerequisites / Detection
+
+```bash
+node skills/wp-content-attribution/scripts/attribution_inspect.mjs --cwd=/path/to/wordpress
+```
+
+The script checks WooCommerce presence, analytics plugins, UTM tracking setup, content/product volume ratio, and existing order meta with source fields.
+
+## Content Attribution Operations Decision Tree
+
+1. **What attribution task?**
+
+   - "UTM tracking" / "campaign tracking" / "source tracking"
+     → **UTM Setup** — Read: `references/utm-tracking-setup.md`
+
+   - "conversion funnel" / "customer journey" / "touchpoints"
+     → **Funnel Analysis** — Read: `references/conversion-funnels.md`
+
+   - "attribution model" / "first touch" / "last touch" / "multi-touch"
+     → **Attribution Models** — Read: `references/attribution-models.md`
+
+   - "content ROI" / "revenue per post" / "cost per acquisition"
+     → **ROI Calculation** — Read: `references/roi-calculation.md`
+
+   - "dashboard" / "report" / "analytics setup"
+     → **Reporting** — Read: `references/reporting-dashboards.md`
+
+2. **Common workflow (first-time setup):**
+   1. Verify WooCommerce + content setup (run `attribution_inspect.mjs`)
+   2. Install UTM capture mu-plugin (see `utm-tracking-setup.md`)
+   3. Tag internal links from content → product pages with UTM parameters
+   4. Wait for data accumulation (minimum 2–4 weeks)
+   5. Pull sales data: `wc_get_sales_report` for period
+   6. Pull content data: `list_content` for same period
+   7. Correlate: match order UTM sources with content pieces
+   8. Apply attribution model (default: last-touch)
+   9. Generate attribution report with top converting content
+
+## Recommended Agent
+
+`wp-ecommerce-manager` — handles WooCommerce data, sales reports, and order analysis with attribution context.
+
+## Additional Resources
+
+### Reference Files
+
+| File | Description |
+|------|-------------|
+| **`references/utm-tracking-setup.md`** | UTM parameter design, mu-plugin for capture, naming conventions |
+| **`references/conversion-funnels.md`** | Funnel stages, drop-off analysis, cart abandonment metrics |
+| **`references/attribution-models.md`** | First-touch, last-touch, linear, time-decay, position-based models |
+| **`references/roi-calculation.md`** | Revenue per post, content ROI formula, CAC, LTV by source |
+| **`references/reporting-dashboards.md`** | GA4 integration, MonsterInsights setup, dashboard KPIs |
+
+### Related Skills
+
+- `wp-woocommerce` — WooCommerce store management and reporting tools
+- `wp-content` — content management and editorial workflows
+- `wp-monitoring` — ongoing site performance and health tracking
+- `wp-content-repurposing` — transform high-ROI content into multi-channel formats

package/skills/wp-content-attribution/references/attribution-models.md

@@ -0,0 +1,189 @@
+# Attribution Models
+
+Use this file when selecting and implementing an attribution model — first-touch, last-touch, linear, time-decay, and position-based approaches for WordPress + WooCommerce content attribution.
+
+## Model Overview
+
+| Model | Credit Distribution | Best For | Complexity |
+|-------|-------------------|----------|------------|
+| **First-Touch** | 100% to first interaction | Brand awareness measurement | Low |
+| **Last-Touch** | 100% to last interaction before purchase | Direct conversion analysis | Low |
+| **Linear** | Equal across all touchpoints | Balanced view of journey | Medium |
+| **Time-Decay** | More to recent touchpoints | Short sales cycles | Medium |
+| **Position-Based (U-shaped)** | 40% first, 40% last, 20% middle | Full journey with key moments | High |
+
+## First-Touch Attribution
+
+Credit goes entirely to the first content interaction that brought the customer.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Blog Post B → Purchase
+Attribution:      Blog Post A = 100%
+```
+
+**WordPress implementation:**
+- Uses the `_first_utm_source` and `_first_utm_campaign` order meta fields
+- Captured via the first-visit cookie in the UTM mu-plugin
+
+**When to use:**
+- You want to understand which content attracts new customers
+- Evaluating top-of-funnel content effectiveness
+- Measuring brand awareness investment ROI
+
+**Limitation:** Ignores all subsequent interactions that nurtured the conversion.
+
+## Last-Touch Attribution
+
+Credit goes entirely to the last content interaction before purchase.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Blog Post B → Purchase
+Attribution:      Blog Post B = 100%
+```
+
+**WordPress implementation:**
+- Uses the `_last_utm_source` and `_last_utm_campaign` order meta fields
+- Captured via the always-updated last-touch cookie
+
+**When to use:**
+- Default starting model (simplest, most actionable)
+- Identifying content that directly triggers purchases
+- Short sales cycles where one touchpoint dominates
+
+**Limitation:** Ignores the content that initially attracted the customer.
+
+## Linear Attribution
+
+Equal credit distributed across all touchpoints in the journey.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Blog Post B → Purchase
+Attribution:      Blog Post A = 33.3%, Product Page = 33.3%, Blog Post B = 33.3%
+```
+
+**WordPress implementation:**
+Requires tracking all touchpoints, not just first and last. Options:
+1. **Session tracking:** Store each page view with UTM in a user session log (more complex mu-plugin)
+2. **GA4 integration:** Use Google Analytics 4's exploration reports for multi-touch paths
+3. **Simplified approach:** Split credit between first-touch and last-touch (50/50)
+
+**When to use:**
+- All content in the journey contributes equally
+- Long sales cycles with many touchpoints
+- Content team needs validation that middle-of-funnel content matters
+
+**Limitation:** Overvalues low-impact touchpoints (e.g., accidental page views).
+
+## Time-Decay Attribution
+
+More credit to touchpoints closer in time to the conversion.
+
+**Logic (example decay: 7-day half-life):**
+```
+Day 1:  Blog Post A (30 days before purchase) = 6%
+Day 15: Product Page (15 days before)         = 18%
+Day 25: Blog Post B (5 days before)           = 31%
+Day 29: Email Link (1 day before)             = 45%
+```
+
+**Formula:**
+```
+Credit = 2^(-(time_before_purchase / half_life))
+Normalize all credits to sum to 100%
+```
+
+**When to use:**
+- Sales cycle is short (< 30 days)
+- Recent interactions are more influential than early ones
+- Evaluating promotional/seasonal content effectiveness
+
+**Limitation:** Undervalues brand awareness content that starts the journey.
+
+## Position-Based (U-shaped) Attribution
+
+40% to first touch, 40% to last touch, 20% distributed across middle touchpoints.
+
+**Logic:**
+```
+Customer journey: Blog Post A → Product Page → Comparison → Blog Post B → Purchase
+Attribution:      Blog Post A = 40%, Product Page = 10%, Comparison = 10%, Blog Post B = 40%
+```
+
+**When to use:**
+- Both acquisition (first touch) and conversion (last touch) are strategically important
+- Multi-step customer journeys with clear awareness and decision phases
+- Most balanced model for content strategy decisions
+
+**Limitation:** Requires full journey tracking; arbitrary 40/40/20 split.
+
+## Choosing the Right Model
+
+```
+Start here:
+    │
+    ├─ "I just need something simple to start"
+    │   → Last-Touch Attribution
+    │
+    ├─ "I want to know what content attracts new customers"
+    │   → First-Touch Attribution
+    │
+    ├─ "My sales cycle is short (< 7 days)"
+    │   → Last-Touch Attribution
+    │
+    ├─ "My sales cycle is medium (7-30 days)"
+    │   → Time-Decay Attribution (7-day half-life)
+    │
+    ├─ "My sales cycle is long (30+ days, many touchpoints)"
+    │   → Position-Based (U-shaped)
+    │
+    └─ "I want to validate all content stages equally"
+        → Linear Attribution
+```
+
+## WordPress-Specific Implementation
+
+### Building Attribution from Order Meta
+
+With the UTM mu-plugin capturing first-touch and last-touch data:
+
+```bash
+# Pull orders with attribution data
+wc_list_orders(status="completed", per_page=100)
+
+# For each order, check meta fields:
+# _first_utm_source, _first_utm_campaign → first-touch attribution
+# _last_utm_source, _last_utm_campaign   → last-touch attribution
+# _landing_page                          → first page visited
+```
+
+### Attribution Report Query
+
+```
+For each unique utm_campaign value in completed orders:
+  1. Count orders with this campaign (first-touch)
+  2. Count orders with this campaign (last-touch)
+  3. Sum revenue for each
+  4. Map campaign name back to content piece (campaign = post slug)
+  5. Rank by revenue
+```
+
+### Simplified Multi-Touch (50/50 First/Last)
+
+When full journey tracking is not available, split attribution between first and last touch:
+
+```
+Revenue per content piece =
+  (orders where _first_utm_campaign = post_slug × order_total × 0.5) +
+  (orders where _last_utm_campaign = post_slug × order_total × 0.5)
+```
+
+## Decision Checklist
+
+1. What is the average sales cycle length? → Short = last-touch; Long = position-based
+2. Is full journey tracking available (all touchpoints)? → No = use first/last touch only
+3. Is the goal to optimize acquisition or conversion content? → Acquisition = first-touch; Conversion = last-touch
+4. Does the team need a simple, actionable model first? → Start with last-touch, evolve later
+5. Are UTM cookies capturing first and last touch? → Verify mu-plugin is installed

package/skills/wp-content-attribution/references/conversion-funnels.md

@@ -0,0 +1,137 @@
+# Conversion Funnels
+
+Use this file when analyzing the content-to-commerce funnel — mapping funnel stages, measuring drop-off, and correlating WooCommerce events with content interactions.
+
+## Content-to-Commerce Funnel Stages
+
+```
+Awareness → Consideration → Decision → Purchase → Retention
+   │              │              │           │           │
+   Blog post      Product page   Cart        Checkout    Re-order
+   Social share   Comparison     Wishlist    Payment     Review
+   SEO landing    Category page  Pricing     Confirm     Referral
+```
+
+### Stage Definitions
+
+| Stage | User Intent | Content Type | WooCommerce Event |
+|-------|------------|--------------|-------------------|
+| **Awareness** | "I have a problem" | Blog posts, guides, educational content | Page view (no WC interaction) |
+| **Consideration** | "What are my options?" | Product pages, comparisons, reviews | Product view, add to wishlist |
+| **Decision** | "I'm choosing this one" | Product detail, pricing, testimonials | Add to cart |
+| **Purchase** | "I'm buying now" | Cart, checkout | Checkout initiated → Order placed |
+| **Retention** | "I'll come back" | Thank-you page, follow-up emails | Re-order, review submitted |
+
+## Funnel Metrics per Stage
+
+| Metric | Formula | Target | Data Source |
+|--------|---------|--------|-------------|
+| **Awareness rate** | Unique blog visitors / Total visitors | > 40% | Google Analytics |
+| **Content→Product rate** | Product page views from blog / Blog page views | > 5% | UTM tracking |
+| **Add-to-cart rate** | Add-to-cart events / Product page views | > 8% | WooCommerce analytics |
+| **Cart→Checkout rate** | Checkout initiated / Add-to-cart events | > 50% | WooCommerce analytics |
+| **Checkout conversion** | Orders placed / Checkout initiated | > 60% | `wc_get_sales_report` |
+| **Overall content→sale** | Orders from blog / Blog visitors | > 0.5% | UTM + order correlation |
+
+## WordPress Content Mapping to Funnel Stages
+
+### Awareness Content (Top of Funnel)
+
+- **Blog posts** — educational, informational, SEO-targeted
+- **Guides/tutorials** — how-to content solving user problems
+- **Infographics/media** — shareable, high-reach content
+- **SEO landing pages** — targeting informational keywords
+
+Query awareness content:
+```bash
+# List recent blog posts (awareness stage content)
+list_content(type="post", status="publish", per_page=50, orderby="date")
+```
+
+### Consideration Content (Middle of Funnel)
+
+- **Product pages** — detailed product information
+- **Category pages** — curated product collections
+- **Comparison posts** — "Product A vs Product B"
+- **Case studies/reviews** — social proof content
+
+### Decision Content (Bottom of Funnel)
+
+- **Product detail with CTA** — pricing, buy button, urgency
+- **Testimonials/reviews** — conversion reinforcement
+- **FAQ pages** — objection handling
+- **Pricing/plans pages** — clear value proposition
+
+## Funnel Drop-Off Analysis
+
+### Identifying Drop-Off Points
+
+```
+Stage               Visitors    Drop-off    Rate
+─────────────────────────────────────────────────
+Blog post view      10,000      -           100%
+Click to product     500        9,500       5.0%
+Add to cart          80         420         16.0%
+Begin checkout       50         30          62.5%
+Complete purchase    35         15          70.0%
+─────────────────────────────────────────────────
+Overall conversion: 35 / 10,000 = 0.35%
+```
+
+### Common Drop-Off Causes and Fixes
+
+| Drop-Off Point | Common Cause | Fix |
+|----------------|-------------|-----|
+| Blog → Product | Weak CTA in blog post | Add prominent product CTA with UTM |
+| Product → Cart | Missing social proof | Add reviews, ratings, trust badges |
+| Cart → Checkout | Unexpected costs (shipping) | Show shipping calculator earlier |
+| Checkout → Purchase | Complex checkout form | Simplify, enable guest checkout |
+| Purchase → Re-order | No follow-up engagement | Set up post-purchase email sequence |
+
+## WooCommerce Cart Abandonment as Funnel Metric
+
+Cart abandonment rate = (Carts created - Orders completed) / Carts created
+
+### Measuring with WooCommerce
+
+```bash
+# Get total orders in period
+wc_get_sales_report(period="month")
+# Returns: total_orders, total_sales, etc.
+
+# Compare with add-to-cart events (requires analytics plugin or custom tracking)
+```
+
+### Abandonment Recovery Strategies
+
+1. **Abandoned cart emails** — send 1h, 24h, 72h after abandonment
+2. **Exit-intent popup** — offer discount at checkout page exit
+3. **Retargeting ads** — Facebook/Google remarketing to cart abandoners
+4. **Simplified checkout** — reduce form fields, add payment options
+
+## Cross-Referencing Sales with Content Dates
+
+Correlate content publication with sales spikes:
+
+```bash
+# Get sales by date range
+wc_get_sales_report(date_min="2025-01-01", date_max="2025-01-31")
+
+# Get content published in same period
+list_content(type="post", status="publish", after="2025-01-01", before="2025-01-31")
+```
+
+**Analysis pattern:**
+1. Pull monthly sales report from WooCommerce
+2. Pull content published that month
+3. Identify sales spikes after content publication
+4. Match spikes with UTM source data on orders
+5. Calculate correlation: content publish date → sales uplift window (typically 1–7 days)
+
+## Decision Checklist
+
+1. Are funnel stages defined and mapped to content types? → Use table above as starting point
+2. Are drop-off rates measured at each stage? → Set up analytics tracking if not
+3. Is cart abandonment rate tracked? → Check WooCommerce reports or analytics plugin
+4. Are content publish dates correlated with sales data? → Cross-reference monthly
+5. Are recovery strategies in place for the biggest drop-off point? → Prioritize highest-impact fix

package/skills/wp-content-attribution/references/reporting-dashboards.md

@@ -0,0 +1,199 @@
+# Reporting Dashboards
+
+Use this file when setting up content attribution reporting — GA4 integration, analytics plugin configuration, dashboard KPIs, and automated reporting workflows.
+
+## WooCommerce + WordPress Analytics Correlation
+
+The core reporting methodology links three data sources:
+
+```
+WordPress Content Data          WooCommerce Order Data         Analytics Data
+(list_content, post dates)  +   (wc_list_orders, order meta) + (GA4, MonsterInsights)
+         │                              │                              │
+         └──────────── Correlate via UTM campaign = post slug ─────────┘
+```
+
+### Manual Correlation Workflow
+
+1. **Export orders** with UTM meta for the reporting period
+2. **Export content** published in the same period
+3. **Match** `_last_utm_campaign` values to post slugs
+4. **Aggregate** revenue per post, per category, per content type
+5. **Rank** by revenue, ROI, or conversion rate
+
+## Google Analytics 4 Integration
+
+### UTM → GA4 → WooCommerce Reconciliation
+
+GA4 automatically captures UTM parameters as session-level dimensions:
+
+| GA4 Dimension | UTM Parameter | Use |
+|---------------|--------------|-----|
+| Session source | `utm_source` | Where traffic came from |
+| Session medium | `utm_medium` | Channel type |
+| Session campaign | `utm_campaign` | Specific campaign/post |
+| Session manual ad content | `utm_content` | Link variant |
+| Session manual term | `utm_term` | Search keyword |
+
+**GA4 Exploration report for content attribution:**
+1. Go to Explore → Free-form
+2. Dimensions: Session campaign, Landing page
+3. Metrics: Sessions, Conversions, Revenue
+4. Filter: Session source = "blog"
+5. Sort by Revenue descending
+
+### Enhanced E-commerce Events
+
+GA4 tracks the full purchase funnel when configured:
+- `view_item` — product page view
+- `add_to_cart` — item added to cart
+- `begin_checkout` — checkout started
+- `purchase` — order completed with revenue
+
+## MonsterInsights / WooCommerce Google Analytics Plugin
+
+### MonsterInsights Setup
+
+MonsterInsights bridges WordPress content data with GA4:
+
+1. **Install:** MonsterInsights plugin (free tier sufficient for basic attribution)
+2. **Connect:** Link to GA4 property via the setup wizard
+3. **Enable:** Enhanced E-commerce tracking in MonsterInsights settings
+4. **Dashboard:** View top posts by revenue directly in WordPress admin
+
+**Key MonsterInsights reports:**
+- Top Landing Pages (awareness stage)
+- Top Outbound Links (consideration stage)
+- E-commerce Revenue by Source (attribution)
+- Top Products (conversion stage)
+
+### WooCommerce Google Analytics Plugin (Official)
+
+Alternative for sites already using GA4 without MonsterInsights:
+
+1. Install: "WooCommerce Google Analytics" (official extension)
+2. Enter GA4 Measurement ID
+3. Enable: Enhanced E-commerce events
+4. Events auto-tracked: `view_item`, `add_to_cart`, `purchase`
+
+## Custom Dashboard Options
+
+### WP Admin Dashboard Widget
+
+Create a simple attribution summary widget:
+
+```php
+add_action('wp_dashboard_setup', function () {
+    wp_add_dashboard_widget(
+        'content_attribution_widget',
+        'Content Attribution — Top 5 Posts by Revenue',
+        function () {
+            // Query recent completed orders with UTM data
+            $orders = wc_get_orders([
+                'status' => 'completed',
+                'limit'  => 100,
+                'date_created' => '>' . date('Y-m-d', strtotime('-30 days')),
+            ]);
+            $revenue_by_campaign = [];
+            foreach ($orders as $order) {
+                $campaign = $order->get_meta('_last_utm_campaign');
+                if ($campaign) {
+                    $revenue_by_campaign[$campaign] = ($revenue_by_campaign[$campaign] ?? 0) + $order->get_total();
+                }
+            }
+            arsort($revenue_by_campaign);
+            echo '<table><tr><th>Content</th><th>Revenue</th></tr>';
+            $i = 0;
+            foreach ($revenue_by_campaign as $campaign => $revenue) {
+                if ($i++ >= 5) break;
+                echo '<tr><td>' . esc_html($campaign) . '</td><td>' . wc_price($revenue) . '</td></tr>';
+            }
+            echo '</table>';
+        }
+    );
+});
+```
+
+### External BI Tools
+
+For larger operations, export data to external dashboards:
+
+| Tool | Integration Method | Cost |
+|------|-------------------|------|
+| Google Looker Studio | GA4 connector + WC data export | Free |
+| Tableau | WooCommerce REST API → CSV/database | Paid |
+| Metabase | Direct MySQL/PostgreSQL connection | Free (self-hosted) |
+| Power BI | REST API connector or CSV import | Paid |
+
+## Automated Reporting
+
+### Monthly Content Attribution Report Template
+
+```
+## Content Attribution Report — {Month} {Year}
+
+### Summary
+- Total content-attributed revenue: ${total}
+- Orders with UTM attribution: {count} ({percentage}% of total orders)
+- Top attribution model used: {model}
+
+### Top 10 Converting Content Pieces
+| Rank | Post | Revenue | Orders | Avg Order Value |
+|------|------|---------|--------|-----------------|
+| 1 | {title} | ${rev} | {n} | ${aov} |
+| ... | ... | ... | ... | ... |
+
+### Revenue by Content Category
+| Category | Revenue | Posts | Revenue/Post |
+|----------|---------|-------|-------------|
+| {cat} | ${rev} | {n} | ${rpp} |
+
+### Revenue by Source
+| Source | Revenue | Orders | CAC |
+|--------|---------|--------|-----|
+| blog | ${rev} | {n} | ${cac} |
+| newsletter | ${rev} | {n} | ${cac} |
+
+### Recommendations
+- Invest more in: {top category}
+- Reduce investment in: {lowest ROI category}
+- Content gap: {opportunity identified}
+```
+
+### Automation via WP-Cron
+
+Schedule monthly report generation:
+
+```php
+// Register cron event
+if (!wp_next_scheduled('generate_attribution_report')) {
+    wp_schedule_event(time(), 'monthly', 'generate_attribution_report');
+}
+
+add_action('generate_attribution_report', function () {
+    // Generate report data (query orders, correlate with content)
+    // Save as a private post or send via email
+    // Uses same logic as dashboard widget but for full month
+});
+```
+
+## Key KPIs Dashboard
+
+The essential metrics for an at-a-glance attribution dashboard:
+
+| KPI | Description | Update Frequency |
+|-----|-------------|-----------------|
+| **Content-Attributed Revenue** | Total revenue from orders with UTM data | Weekly |
+| **Top Converting Post** | Post with highest attributed revenue this month | Monthly |
+| **Attribution Rate** | % of orders with UTM attribution data | Weekly |
+| **Content ROI** | (Revenue - Cost) / Cost × 100% | Monthly |
+| **CAC by Source** | Customer acquisition cost per channel | Monthly |
+| **Revenue/Post Trend** | Month-over-month revenue per post | Monthly |
+
+## Decision Checklist
+
+1. Is GA4 connected and tracking enhanced e-commerce events? → Verify in GA4 Realtime report
+2. Is MonsterInsights or equivalent analytics plugin active? → Check WordPress admin dashboard
+3. Are WooCommerce orders showing UTM meta data? → Spot-check 5 recent orders
+4. Is a monthly report process defined (manual or automated)? → Set up template + schedule
+5. Are KPIs reviewed and actioned on regularly? → Schedule monthly review meeting