@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/analytics-tracking/references/gtm-implementation.md

@@ -0,0 +1,390 @@
+# Google Tag Manager Implementation Reference
+
+Detailed guide for implementing tracking via Google Tag Manager.
+
+## Contents
+- Container Structure (tags, triggers, variables)
+- Naming Conventions
+- Data Layer Patterns
+- Common Tag Configurations (GA4 configuration tag, GA4 event tag, Facebook pixel)
+- Preview and Debug
+- Workspaces and Versioning
+- Consent Management
+- Advanced Patterns (tag sequencing, exception handling, custom JavaScript variables)
+
+## Container Structure
+
+### Tags
+
+Tags are code snippets that execute when triggered.
+
+**Common tag types:**
+- GA4 Configuration (base setup)
+- GA4 Event (custom events)
+- Google Ads Conversion
+- Facebook Pixel
+- LinkedIn Insight Tag
+- Custom HTML (for other pixels)
+
+### Triggers
+
+Triggers define when tags fire.
+
+**Built-in triggers:**
+- Page View: All Pages, DOM Ready, Window Loaded
+- Click: All Elements, Just Links
+- Form Submission
+- Scroll Depth
+- Timer
+- Element Visibility
+
+**Custom triggers:**
+- Custom Event (from dataLayer)
+- Trigger Groups (multiple conditions)
+
+### Variables
+
+Variables capture dynamic values.
+
+**Built-in (enable as needed):**
+- Click Text, Click URL, Click ID, Click Classes
+- Page Path, Page URL, Page Hostname
+- Referrer
+- Form Element, Form ID
+
+**User-defined:**
+- Data Layer variables
+- JavaScript variables
+- Lookup tables
+- RegEx tables
+- Constants
+
+---
+
+## Naming Conventions
+
+### Recommended Format
+
+```
+[Type] - [Description] - [Detail]
+
+Tags:
+GA4 - Event - Signup Completed
+GA4 - Config - Base Configuration
+FB - Pixel - Page View
+HTML - LiveChat Widget
+
+Triggers:
+Click - CTA Button
+Submit - Contact Form
+View - Pricing Page
+Custom - signup_completed
+
+Variables:
+DL - user_id
+JS - Current Timestamp
+LT - Campaign Source Map
+```
+
+---
+
+## Data Layer Patterns
+
+### Basic Structure
+
+```javascript
+// Initialize (in <head> before GTM)
+window.dataLayer = window.dataLayer || [];
+
+// Push event
+dataLayer.push({
+  'event': 'event_name',
+  'property1': 'value1',
+  'property2': 'value2'
+});
+```
+
+### Page Load Data
+
+```javascript
+// Set on page load (before GTM container)
+window.dataLayer = window.dataLayer || [];
+dataLayer.push({
+  'pageType': 'product',
+  'contentGroup': 'products',
+  'user': {
+    'loggedIn': true,
+    'userId': '12345',
+    'userType': 'premium'
+  }
+});
+```
+
+### Form Submission
+
+```javascript
+document.querySelector('#contact-form').addEventListener('submit', function() {
+  dataLayer.push({
+    'event': 'form_submitted',
+    'formName': 'contact',
+    'formLocation': 'footer'
+  });
+});
+```
+
+### Button Click
+
+```javascript
+document.querySelector('.cta-button').addEventListener('click', function() {
+  dataLayer.push({
+    'event': 'cta_clicked',
+    'ctaText': this.innerText,
+    'ctaLocation': 'hero'
+  });
+});
+```
+
+### E-commerce Events
+
+```javascript
+// Product view
+dataLayer.push({ ecommerce: null }); // Clear previous
+dataLayer.push({
+  'event': 'view_item',
+  'ecommerce': {
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'item_category': 'Category',
+      'quantity': 1
+    }]
+  }
+});
+
+// Add to cart
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  'event': 'add_to_cart',
+  'ecommerce': {
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'quantity': 1
+    }]
+  }
+});
+
+// Purchase
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  'event': 'purchase',
+  'ecommerce': {
+    'transaction_id': 'T12345',
+    'value': 99.99,
+    'currency': 'USD',
+    'tax': 5.00,
+    'shipping': 10.00,
+    'items': [{
+      'item_id': 'SKU123',
+      'item_name': 'Product Name',
+      'price': 99.99,
+      'quantity': 1
+    }]
+  }
+});
+```
+
+---
+
+## Common Tag Configurations
+
+### GA4 Configuration Tag
+
+**Tag Type:** Google Analytics: GA4 Configuration
+
+**Settings:**
+- Measurement ID: G-XXXXXXXX
+- Send page view: Checked (for pageviews)
+- User Properties: Add any user-level dimensions
+
+**Trigger:** All Pages
+
+### GA4 Event Tag
+
+**Tag Type:** Google Analytics: GA4 Event
+
+**Settings:**
+- Configuration Tag: Select your config tag
+- Event Name: {{DL - event_name}} or hardcode
+- Event Parameters: Add parameters from dataLayer
+
+**Trigger:** Custom Event with event name match
+
+### Facebook Pixel - Base
+
+**Tag Type:** Custom HTML
+
+```html
+<script>
+  !function(f,b,e,v,n,t,s)
+  {if(f.fbq)return;n=f.fbq=function(){n.callMethod?
+  n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+  if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
+  n.queue=[];t=b.createElement(e);t.async=!0;
+  t.src=v;s=b.getElementsByTagName(e)[0];
+  s.parentNode.insertBefore(t,s)}(window, document,'script',
+  'https://connect.facebook.net/en_US/fbevents.js');
+  fbq('init', 'YOUR_PIXEL_ID');
+  fbq('track', 'PageView');
+</script>
+```
+
+**Trigger:** All Pages
+
+### Facebook Pixel - Event
+
+**Tag Type:** Custom HTML
+
+```html
+<script>
+  fbq('track', 'Lead', {
+    content_name: '{{DL - form_name}}'
+  });
+</script>
+```
+
+**Trigger:** Custom Event - form_submitted
+
+---
+
+## Preview and Debug
+
+### Preview Mode
+
+1. Click "Preview" in GTM
+2. Enter site URL
+3. GTM debug panel opens at bottom
+
+**What to check:**
+- Tags fired on this event
+- Tags not fired (and why)
+- Variables and their values
+- Data layer contents
+
+### Debug Tips
+
+**Tag not firing:**
+- Check trigger conditions
+- Verify data layer push
+- Check tag sequencing
+
+**Wrong variable value:**
+- Check data layer structure
+- Verify variable path (nested objects)
+- Check timing (data may not exist yet)
+
+**Multiple firings:**
+- Check trigger uniqueness
+- Look for duplicate tags
+- Check tag firing options
+
+---
+
+## Workspaces and Versioning
+
+### Workspaces
+
+Use workspaces for team collaboration:
+- Default workspace for production
+- Separate workspaces for large changes
+- Merge when ready
+
+### Version Management
+
+**Best practices:**
+- Name every version descriptively
+- Add notes explaining changes
+- Review changes before publish
+- Keep production version noted
+
+**Version notes example:**
+```
+v15: Added purchase conversion tracking
+- New tag: GA4 - Event - Purchase
+- New trigger: Custom Event - purchase
+- New variables: DL - transaction_id, DL - value
+- Tested: Chrome, Safari, Mobile
+```
+
+---
+
+## Consent Management
+
+### Consent Mode Integration
+
+```javascript
+// Default state (before consent)
+gtag('consent', 'default', {
+  'analytics_storage': 'denied',
+  'ad_storage': 'denied'
+});
+
+// Update on consent
+function grantConsent() {
+  gtag('consent', 'update', {
+    'analytics_storage': 'granted',
+    'ad_storage': 'granted'
+  });
+}
+```
+
+### GTM Consent Overview
+
+1. Enable Consent Overview in Admin
+2. Configure consent for each tag
+3. Tags respect consent state automatically
+
+---
+
+## Advanced Patterns
+
+### Tag Sequencing
+
+**Setup tags to fire in order:**
+Tag Configuration > Advanced Settings > Tag Sequencing
+
+**Use cases:**
+- Config tag before event tags
+- Pixel initialization before tracking
+- Cleanup after conversion
+
+### Exception Handling
+
+**Trigger exceptions** - Prevent tag from firing:
+- Exclude certain pages
+- Exclude internal traffic
+- Exclude during testing
+
+### Custom JavaScript Variables
+
+```javascript
+// Get URL parameter
+function() {
+  var params = new URLSearchParams(window.location.search);
+  return params.get('campaign') || '(not set)';
+}
+
+// Get cookie value
+function() {
+  var match = document.cookie.match('(^|;) ?user_id=([^;]*)(;|$)');
+  return match ? match[2] : null;
+}
+
+// Get data from page
+function() {
+  var el = document.querySelector('.product-price');
+  return el ? parseFloat(el.textContent.replace('$', '')) : 0;
+}
+```

package/skills/article-generator/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: article-generator
+description: >
+  Multi-format article generator router. Delegates to the right sub-skill based on
+  available inputs: YouTube→NLM research, NLM mindmap hub & spoke, or keyword-driven SEO.
+  All sub-skills read brand intelligence from evergreen brand-assets.
+  Use when: generating articles, blog posts, hub & spoke content, NLM to article,
+  YouTube research for articles, SEO article, content generation for any brand.
+depends-on:
+  - hook-generator
+  - sharp-thesis-validator
+---
+
+# Article Generator
+
+Routes to the right sub-skill based on what you have. Three paths, one brand intelligence source.
+
+## Phase 0: Awareness Gate (MANDATORY)
+
+Before any copy work, determine the target audience's awareness level:
+
+1. **Can you determine awareness level from the prompt/context?**
+   - For SEO: keyword intent maps to awareness level
+     - Informational ("how to fix X") → Problem-aware
+     - Comparative ("X vs Y") → Solution-aware
+     - Branded ("your product") → Product-aware
+     - Transactional ("buy X") → Most-aware
+   - For social: content topic + audience → awareness level
+   - For email: subscriber stage → awareness level
+
+2. **If YES** → Proceed with awareness-matched strategy
+   - Load `references/awareness-level-guide.md`
+   - Select copy framework based on awareness level
+
+3. **If NO** → ASK THE USER before proceeding:
+   "What awareness level is your target audience at?"
+   - Unaware — doesn't know they have a problem
+   - Problem-aware — knows the problem, doesn't know solutions exist
+   - Solution-aware — knows solutions exist, doesn't know your product
+   - Product-aware — knows your product, not convinced it's right
+   - Most-aware — ready to buy, just needs the offer
+
+## Phase 1: Sharp-Thesis Validation (MANDATORY — Applied Before Writing)
+
+Before proceeding to any mode, validate the topic/title using the Sharp-Thesis (Cerebras) Test:
+
+```
+sharp-thesis-validator --mode long-form --brand {brand} "{topic/title}"
+```
+
+**On PASS:** Proceed to Mode Router.
+**On FAIL:** STOP and return reframing suggestions to Jairo. Do not proceed to research or writing.
+
+### Validation Requirements:
+- **Single arguable claim** (not "X is important" but "X does Y because Z")
+- **Concrete number** (dollar figure, percentage, timeframe, count)
+- **Urgency** (time-bound trigger, not evergreen)
+- **Title expressibility** (≤80 chars for magazine-cover style)
+
+### Brand Context Loading:
+- Loads brand-assets from evergreen path: `businesses/nomadixgear-sa/{brand}/brand-assets/`
+- Reads: `thesis-config.md`, `icp-profiles.md`, `business-profile.md`, `competitive-analysis.md`
+- Enriches reframe suggestions with brand-specific numbers and positioning
+
+### Mode Router
+
+Three modes. Pick based on what you have:
+
+### Mode A: Keyword → SEO Article
+**When:** You only have a keyword or topic (no NLM notebook).
+**Action:** Delegate to `seo-content` skill. Keyword→article with brand intelligence, no NLM needed.
+
+### Mode B: NLM Mindmap → Hub & Spoke Articles
+**When:** You have an existing NLM mindmap/notebook with nodes.
+**Action:** Delegate to `nlm-hub-spoke` skill. Generates hub pages first, then spoke articles per hub. Each article gets a human version + AEO counterpart.
+
+### Mode C: YouTube → NotebookLM → Hub & Spoke
+**When:** You have a YouTube video or channel to research first, no existing NLM notebook.
+**Action:** Delegate to `youtube-notebooklm-research` skill for research phase. After NLM notebook + mindmap is created, continue with Mode B (`nlm-hub-spoke`) for writing phase.
+
+**Sub-skills and their jobs:**
+- `seo-content` — Keyword → SEO article (Mode A, writing phase without NLM)
+- `nlm-hub-spoke` — NLM mindmap → hub & spoke articles (Mode B, writing phase with NLM)
+- `youtube-notebooklm-research` — YouTube → NLM notebook + mindmap (Mode C, research phase)
+
+**When delegating, pass along:**
+- Brand name
+- Evergreen brand-assets path
+- landscape.md path (if exists at `{brand-assets}/landscape.md`)
+- first-party-data.md path (if exists at `{brand-assets}/first-party-data.md`)
+- Topic/keyword
+- Any enrichment files relevant to the topic
+
+**Path contract:** The sub-skill (seo-content for Mode A) MUST use the passed landscape.md path directly (step 1 resolve → step 8 read), not re-resolve from its own convention. If no landscape.md path is passed, check at resolved brand dir.
+
+### Brand Naming & Claims Rules (MANDATORY — Applied Before Writing)
+
+Every article MUST comply with the brand's naming conventions and claims blacklist. Load these from the brand's `competitive-reference.md` (if it exists) or `landscape.md`:
+
+**Product naming:**
+- Use the brand's product names as they appear in `products.md` (e.g., "Gome Clan," not "portable shelter model")
+- Match ICP search language in SEO titles/h2s (e.g., "luxury camping tent," "glamping tent")
+- Never use banned terms (e.g., "dome" for NomadixGear — always "glamping tent")
+
+**Claims blacklist (hard gate):**
+- Load `landscape.md` or `competitive-reference.md` and read the claims blacklist section
+- Any claim in the blacklist MUST NOT appear in the article
+- This includes taglines (e.g., "World's Most Advanced Portable Shelter" is blacklisted for some brands)
+- Only use claims from the "Verified Safe Claims" section
+
+**Product data accuracy:**
+- Read `products.md` for specifications — never make up or estimate dimensions/prices
+- When specs are behind a login wall (e.g., "Login to see price"), use Zoho Books pricing data if available
+- Material tiers (e.g., Semi-Permanent vs Permanent) must be accurately distinguished
+
+**Cron scheduling:** When creating scheduled tasks (`kimaki send`) for article generation, use `--agent plan`. The plan agent handles research and outline phases better. After approval, switch to build agent for execution.
+
+## Downstream Pipeline
+
+After any sub-skill produces a draft article, chain into:
+1. **seo-content (Phase N3)** — Generate hooks/titles (MANDATORY — never skip). seo-content now includes hook-generator subagent integration for SEO title scoring.
+2. **blog-publish-pipeline** — WordPress publishing with human + AEO pairs
+
+**Hook-generator integration:** The seo-content sub-skill handles hook generation internally. If running article-generator outside the seo-content pipeline, spawn a hook-generator subagent directly for article titles:
+```
+Load the hook-generator skill and execute the full Phase 1-6 pipeline with this context.
+Context:
+- WHO: <ICP from brand assets>
+- WHAT/WHY: <article's core thesis>
+- Knife: <primary misconception or pain>
+- Platform: medium
+- Brand: <brand name>
+- Target Score: 85
+Return ONLY this JSON array: [{"hook":"...","score":<0-100>,"pattern":"...","formula":"..."}]
+```
+If subagent fails, use keyword + benefit formula for titles.
+
+**Flow:** sub-skill output → seo-content Phase N3 → blog-publish-pipeline
+
+## Brand Intelligence
+
+All sub-skills share the same brand intelligence source:
+
+**Primary (evergreen):** `businesses/nomadixgear-sa/{brand}/brand-assets/`
+**Fallback (newsletter):** `brands/{brand}/content/00-assets/`
+
+**Core files (all sub-skills load these):**
+| File | Purpose |
+|------|---------|
+| `voice-guide.md` | Brand voice, tone, writing style |
+| `business-profile.md` | Business model, ICP, market position |
+| `icp-profiles.md` | Ideal customer profiles, pain points |
+| `products.md` | Full product catalog |
+| `brand-overrides.md` | Material rules, banned terms, positioning constraints (if exists, fallback: claims blacklist in `landscape.md` or `competitive-reference.md`) |
+
+**Funnel grounding (if `funnel_id` provided):**
+Read `funnels/{funnel_id}-*.md` from the brand's `funnels/` directory before writing.
+Every output article MUST include: `funnel_id`, `buyer_stage`, `cta`, `icp_segment`.
+If the article's CTA doesn't match the funnel's conversion step, STOP and fix it.
+When no funnel_id is provided, proceed without funnel constraints.
+
+**Selective enrichment (topic-matched, 2-3KB each):**
+| If topic matches | Load this file |
+|------------------|----------------|
+| pricing, cost, budget | `official-pricing.md` |
+| vs, compare, alternative, competitor | `competitive-analysis.md` |
+| specs, dimensions, materials | `technical-specifications.md` |
+| materials, fabric, durability | `knowledge-base.txt` |
+
+NEVER load entire enrichment files. Extract only the relevant section.
+
+---
+
+## STEP N: Copywriting Tournament (RECOMMENDED for headlines + CTAs)
+
+Generate 3-5 variants of the key headlines + CTAs, then run them through 5 parallel judge personas to find the winner:
+
+1. Generate 3-5 variants (different angles, formulas, or approaches)
+2. Save each to: `content/tournaments/{slug}/variant-1.md` through `variant-N.md`
+3. Spawn 5 PARALLEL `build` subagents (one per judge persona):
+   - `~/.claude/skills/quality-gate/judge-personas/skeptic.md`
+   - `~/.claude/skills/quality-gate/judge-personas/scanner.md`
+   - `~/.claude/skills/quality-gate/judge-personas/buyer.md`
+   - `~/.claude/skills/quality-gate/judge-personas/expert.md`
+   - `~/.claude/skills/quality-gate/judge-personas/outsider.md`
+   - Each gets: tournament_dir, variant_count, mode=`copy`, original_prompt
+4. Collect all 5 JSON results, aggregate: sum weighted_avg per variant across judges
+5. Pick winner, apply recommended_edits, save as draft
+6. Winner enters standard quality-gate below
+
+**When to use:** For the article headline and CTA sections
+
+---
+
+## FINAL STEP: Quality Gate (MANDATORY — DO NOT SKIP)
+
+Before presenting ANY draft to Jairo, run the quality gate:
+
+1. Save your complete draft to a file (e.g., `content/drafts/{slug}.md` or a temp file)
+2. Spawn a `build` subagent using the Task tool with the quality-gate prompt from `Skill: quality-gate`
+3. Pass these inputs to the subagent:
+   - **draft_path**: absolute path to the saved draft
+   - **mode**: `blog`
+   - **original_prompt**: the writing prompt that started this task
+   - **attempt**: current attempt number (start at 1)
+4. Parse the JSON result from the subagent
+5. If FAIL and attempt < 3:
+   - Rewrite the draft addressing the specific `rewrite_instructions` from the quality gate
+   - Save the new draft (overwrite or new file)
+   - Spawn another subagent with attempt + 1
+6. If FAIL and attempt = 3:
+   - Present to Jairo with all score reports attached
+   - Say: "Couldn't pass quality gate after 3 attempts. Here's what's wrong and what I tried to fix."
+7. If PASS:
+   - Present to Jairo as normal (do NOT show scores — they're internal)
+8. NEVER present a draft that hasn't passed quality gate (except after 3 failed attempts)