@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/sharp-thesis-validator/SKILL.md

@@ -0,0 +1,393 @@
+---
+name: sharp-thesis-validator
+description: Validate that a topic or title passes the Sharp-Thesis (Cerebras) Test before writing begins — single arguable claim, concrete number, urgency, and title length limits. Use when validating article titles, selecting topics, planning content, or filtering NLM mindmap nodes.
+---
+
+# sharp-thesis-validator
+
+**Purpose:** Validate that a topic/title passes the Sharp-Thesis (Cerebras) Test before writing begins. Requires a single arguable claim, a concrete number, urgency, and a title expressible in ≤80 chars (long-form) or ≤280 chars (social). Brand-agnostic — loads evergreen brand-assets for context-aware validation.
+
+> **Invocation (two ways):**
+> 1. **CLI (deterministic — for scripts, cron, kanban workers):**
+>    `sharp-thesis-validator "<title>" --brand <brand> [--mode long-form|social] [--json]`
+>    Installed at `~/clawd/scripts/validate-thesis.mjs`, symlinked to `~/.local/bin/sharp-thesis-validator`.
+>    Exit codes: 0 = PASS, 1 = FAIL, 2 = usage error. `--json` emits the verdict schema below.
+>    Note: the CLI counts only numbers present IN the title and prints rule-based fix hints.
+> 2. **Interactive (for brand-aware reframe suggestions):** load via
+>    `skill("sharp-thesis-validator")` — the agent can additionally enrich from brand
+>    pricing/ICP files (official-pricing.md, icp-profiles.md) that the CLI does not read.
+
+**Use when:** validating article titles, selecting topics, planning content, filtering NLM mindmap nodes, pre-checking before any writing skill, validating social post hooks.
+
+---
+
+## Configuration
+
+```yaml
+name: sharp-thesis-validator
+description: >
+  Validates topics/titles against the Sharp-Thesis (Cerebras) Test.
+  Requires: single arguable claim, concrete number, urgency, title ≤80/280 chars.
+  Brand-agnostic — loads evergreen brand-assets for context.
+  Use when: validating titles, selecting topics, pre-writing checks.
+depends-on: []
+triggers:
+  - validate thesis
+  - sharp thesis
+  - cerebras test
+  - topic validation
+  - is this topic sharp enough
+  - validate title
+  - validate hook
+mode:
+  - long-form  # ≤80 chars, all criteria strict
+  - social     # ≤280 chars, urgency relaxed
+allowed-tools:
+  - Read
+  - Glob
+  - Bash
+```
+
+---
+
+## Execution Flow
+
+### Step 1: Parse Input
+
+Extract from user input:
+- **topic** or **title** (required)
+- **brand** (optional, e.g., "enchantents", "nomadixgear", "aiwithjai")
+- **mode** (optional, default "long-form"; options: "long-form", "social")
+
+If no brand provided → run universal-only validation (no brand enrichment).
+
+### Step 2: Resolve Brand Assets
+
+```
+Primary path: businesses/{parent}/{brand}/brand-assets/
+Fallback path: brands/{brand}/content/00-assets/
+If neither exists → proceed with universal rules only
+```
+
+**Load these files (graceful degradation — skip missing):**
+| File | Purpose |
+|------|---------|
+| `voice-guide.md` | Title tone, writing style |
+| `icp-profiles.md` | What numbers resonate with this ICP |
+| `business-profile.md` | Market context, what "urgency" means |
+| `brand-overrides.md` | Banned claims, positioning constraints |
+| `landscape.md` | Claims blacklist |
+| `thesis-config.md` | Brand-specific overrides (optional) |
+| `official-pricing.md` | Dollar figures for number suggestions |
+| `technical-specifications.md` | Specs for concrete numbers |
+
+### Step 3: Load thesis-config.md (if exists)
+
+Override universal defaults:
+```yaml
+# thesis-config.md example
+number_style:
+  currency: USD
+  preferred_metrics: [ROI, payback_period, lifespan_years, replacement_cost]
+  number_format: digits
+
+title_preferences:
+  max_length: 72  # override default 80
+  allow_colons: false
+  style: magazine_cover
+
+urgency_triggers:
+  - Hurricane season (June-November)
+  - Replacement cycle year 2-3
+  - New competitor entering market
+
+banned_patterns:
+  - "X is the future"
+  - "Why you need X"
+  - "The ultimate guide to X"
+
+social:
+  max_length: 200
+  urgency_required: false
+```
+
+### Step 4: Validate Against 4 Criteria
+
+#### Criterion 1: Single Arguable Claim
+```
+PASS: "X does Y because Z" — a position someone could disagree with
+FAIL: "X is important" / "All about X" / survey-style topic
+
+Test: Can a reasonable person argue against this?
+```
+
+**Detection logic:**
+- Look for causal language: "because", "causes", "costs", "beats", "outperforms"
+- Look for comparative language: "more than", "vs", "better than", "cheaper than"
+- Reject descriptive-only: "is", "has", "includes", "about"
+- Reject survey language: "guide to", "overview of", "introduction to"
+
+#### Criterion 2: Concrete Number
+```
+PASS: Dollar figure, percentage, timeframe, count, ratio
+FAIL: "lots of money" / "significant savings" / "many customers"
+
+Test: Strip the number out — does the claim lose its engine?
+```
+
+**Detection logic (regex patterns):**
+- Currency: `\$[\d,]+(\.\d{2})?` or `USD[\d,]+` or `€[\d,]+` or `£[\d,]+`
+- Percentage: `\d+%` or `percent`
+- Timeframe: `\d+\s*(years?|months?|weeks?|days?|hours?)`
+- Count: `\d+\s*(units?|customers?|users?|posts?|articles?)`
+- Ratio: `\d+:\d+` or `\d+x` (e.g., "10x", "3:1")
+
+#### Criterion 3: Urgency / Why Now
+```
+PASS: Time-bound trigger (season, deadline, regulatory change, market shift,
+      competitor failure, new data, product launch)
+FAIL: "it's always been true" / evergreen only with no time delta
+
+Test: Would this article be less urgent in 6 months?
+      If no urgency delta → FAIL.
+```
+
+**Detection logic:**
+- Time markers: "2026", "this year", "now", "before", "deadline", "season"
+- Event markers: "launch", "change", "new", "shift", "crisis", "update"
+- Comparative urgency: "vs last year", "since", "for the first time"
+- Brand enrichment: check thesis-config.md for brand-specific urgency triggers
+
+**Social mode relaxation:**
+- If mode="social" AND thesis-config.social.urgency_required=false
+- Then urgency is OPTIONAL
+- Otherwise: required for both modes
+
+#### Criterion 4: Title Expressibility (≤max_length chars)
+```
+PASS: Thesis fits in title under max_length
+FAIL: Needs subtitle to make sense, or exceeds character limit
+
+Default max_length:
+  - long-form: 80 chars
+  - social: 280 chars (tweet length)
+Override: thesis-config.title_preferences.max_length or thesis-config.social.max_length
+```
+
+**Test:**
+1. Write the title from the topic
+2. Count characters (including spaces)
+3. Check against limit
+4. No colons-as-cheating (unless thesis-config.title_preferences.allow_colons=true)
+
+### Step 5: Generate Output
+
+#### On PASS (all 4 criteria met):
+```json
+{
+  "result": "PASS",
+  "title": "Why cheap glamping fabric costs more than hurricane damage",
+  "title_length": 56,
+  "criteria": {
+    "1_claim": { "passed": true, "detected_claim": "Cheap fabric replacement cycles cost more than hurricane damage" },
+    "2_number": { "passed": true, "detected_number": "$168,960 vs $25,000" },
+    "3_urgency": { "passed": true, "detected_urgency": "Tropical UV degradation runs 2x faster, replacement cycles accelerating" },
+    "4_title_length": { "passed": true, "length": 56, "max_allowed": 80 }
+  },
+  "mode": "long-form",
+  "action": "PROCEED"
+}
+```
+
+#### On FAIL (any criterion failed):
+```json
+{
+  "result": "FAIL",
+  "topic": "Glamping tents are durable",
+  "failed_criteria": [1, 2, 3],
+  "failures": {
+    "1": {
+      "criterion": "single_arguable_claim",
+      "reason": "Not an arguable claim — 'durable' is a description, not a position",
+      "fix": "Reframe as: 'X outperforms Y because Z'"
+    },
+    "2": {
+      "criterion": "concrete_number",
+      "reason": "No concrete number found",
+      "fix": "Add a dollar figure, percentage, or timeframe"
+    },
+    "3": {
+      "criterion": "urgency",
+      "reason": "No time-bound urgency — true today, true in 2026, true in 2030",
+      "fix": "Add a time trigger: 'before hurricane season', 'in 2026', etc."
+    }
+  },
+  "reframe_suggestions": [
+    {
+      "title": "Why cheap fabric costs more than hurricane damage",
+      "rationale": "Uses pricing data from brand-assets/official-pricing.md",
+      "source_file": "official-pricing.md"
+    },
+    {
+      "title": "The $2,800 cover that outlasts 5 cheaper replacements",
+      "rationale": "Lifespan comparison from brand-assets/technical-specifications.md",
+      "source_file": "technical-specifications.md"
+    }
+  ],
+  "claims_blacklist_hits": [],
+  "mode": "long-form",
+  "action": "BLOCKED — reframe topic before proceeding"
+}
+```
+
+### Step 6: Claims Blacklist Check (Always Runs)
+
+If brand was provided AND brand-assets loaded:
+1. Read `brand-overrides.md` → extract banned claims
+2. Read `landscape.md` → extract "Claims Blacklist" section
+3. Read `thesis-config.md` → extract `banned_patterns`
+4. Check proposed title against all banned patterns
+5. If hits found → add to `claims_blacklist_hits` array in output
+
+**This check is additive — a topic can pass 4 criteria but still FAIL if it hits the blacklist.**
+
+---
+
+## Mode Switching
+
+Determine mode from input:
+```
+--mode long-form  → use long-form limits (default)
+--mode social     → use social limits
+```
+
+Or infer from calling skill:
+- Called by article-generator, blog-worker, nlm-hub-spoke → long-form
+- Called by social-construction, x-post-generator-openclaw, content-atomizer → social
+
+Apply limits:
+| Criterion | long-form | social |
+|-----------|-----------|--------|
+| Title max length | 80 (or thesis-config override) | 280 (or thesis-config.social override) |
+| Urgency required | Always | Only if thesis-config.social.urgency_required != false |
+| Claim (single arguable) | Required | Required |
+| Number (concrete) | Required | Required |
+
+---
+
+## Brand-Aware Reframe Engine
+
+When generating reframe suggestions on FAIL:
+
+1. **Read official-pricing.md** → extract dollar figures for number suggestions
+2. **Read icp-profiles.md** → match pain points to urgency triggers
+3. **Read technical-specifications.md** → find concrete specs (dimensions, lifespan, materials)
+4. **Read landscape.md** → check claims blacklist before suggesting
+5. **Read thesis-config.md** → apply brand-specific title preferences
+
+Generate 2-3 reframe suggestions that:
+- Pass all 4 criteria
+- Use brand-specific numbers/pricing
+- Avoid blacklist hits
+- Match voice/tone from voice-guide.md
+
+---
+
+## Examples
+
+### Long-form PASS
+```
+Input: "Why cheap glamping fabric costs more than hurricane damage"
+Brand: enchantents
+Mode: long-form
+
+Output: {
+  "result": "PASS",
+  "title": "Why cheap glamping fabric costs more than hurricane damage",
+  "title_length": 56,
+  "criteria": {...all passed...},
+  "action": "PROCEED"
+}
+```
+
+### Long-form FAIL
+```
+Input: "Glamping tents are durable"
+Brand: enchantents
+Mode: long-form
+
+Output: {
+  "result": "FAIL",
+  "failed_criteria": [1, 2, 3],
+  "failures": {...},
+  "reframe_suggestions": [...],
+  "action": "BLOCKED"
+}
+```
+
+### Social PASS
+```
+Input: "Survived 3 hurricane seasons with zero patches. This $2,800 fabric isn't cheap — it's cheap to replace."
+Brand: nomadixgear
+Mode: social
+
+Output: {
+  "result": "PASS",
+  "title_length": 108,
+  "criteria": {...all passed (urgency relaxed)...},
+  "action": "PROCEED"
+}
+```
+
+### Social FAIL
+```
+Input: "Our glamping tents are the best! DM for details."
+Brand: nomadixgear
+Mode: social
+
+Output: {
+  "result": "FAIL",
+  "failed_criteria": [1, 2],
+  "failures": {...},
+  "reframe_suggestions": [...],
+  "action": "BLOCKED"
+}
+```
+
+---
+
+## Usage
+
+### Direct Call
+```
+sharp-thesis-validator "Why cheap fabric costs more than hurricane damage" --brand enchantents --mode long-form
+```
+
+### From Another Skill
+```javascript
+const validator = require('sharp-thesis-validator');
+const result = await validator.validate({
+  topic: "Why cheap fabric costs more than hurricane damage",
+  brand: "enchantents",
+  mode: "long-form"
+});
+
+if (result.result === "FAIL") {
+  // Block pipeline, show reframe suggestions
+  console.log("Topic failed Sharp-Thesis Test:", result.failures);
+  console.log("Reframe suggestions:", result.reframe_suggestions);
+  process.exit(1);
+}
+```
+
+### From Kanban Task
+```yaml
+- id: thesis-validation
+  name: "Validate sharp thesis"
+  skill: sharp-thesis-validator
+  args:
+    topic: "{{topic}}"
+    brand: "{{tenant}}"
+    mode: "long-form"
+  gate: true  # blocks downstream until PASS
+```

package/skills/sharp-thesis-validator/examples.md

@@ -0,0 +1,186 @@
+# Sharp-Thesis Validator Examples
+
+Reference examples for pass/fail behavior across industries and modes.
+
+---
+
+## Enchantents (B2B Glamping/Resort Development)
+
+### Long-form PASS
+
+| Input | Result | Reason |
+|-------|--------|--------|
+| "Why cheap glamping fabric costs more than hurricane damage" | PASS | Single claim (fabric > hurricane cost), number ($168,960 vs $25K), urgency (tropical UV 2x faster), 56 chars |
+| "The 6-unit resort that pays back in 14 months" | PASS | Claim (pays back fast), number (6-unit, 14 months), urgency (payback window), 44 chars |
+| "How one developer's 44,000-person waitlist terrifies hotel chains" | PASS | Claim (waitlist threatens hotels), number (44,000), urgency (competitive threat), 64 chars |
+| "Why skipping glamping tent maintenance costs $25,000 per unit per season" | PASS | Claim (skipping maintenance costs), number ($25,000), urgency (per season), 68 chars |
+
+### Long-form FAIL
+
+| Input | Failed Criteria | Why |
+|-------|-----------------|-----|
+| "Glamping tents are durable" | 1, 2, 3 | Descriptive, no number, no urgency |
+| "All about glamping fabric options" | 1, 2, 3 | Survey topic, no claim, no number, no urgency |
+| "Why you need marine-grade acrylic" | 1, 3 | "Why you need" is not a claim; no urgency |
+| "The ultimate guide to glamping tent fabrics" | 1, 2, 3 | Survey, no claim, no number, no urgency |
+| "Glamping fabric durability matters" | 1, 2, 3 | Descriptive, no concrete number, no urgency |
+
+### Social PASS
+
+| Input | Result | Reason |
+|-------|--------|--------|
+| "Survived 3 hurricane seasons with zero patches. This $2,800 fabric isn't cheap — it's cheap to replace." | PASS | Claim (fabric survives), number ($2,800), urgency relaxed (social), 108 chars |
+| "6-unit resort saves $152K/decade by buying the right fabric once. Thread: why most get this wrong." | PASS | Claim (saves money), number ($152K, decade), urgency relaxed, 95 chars |
+
+### Social FAIL
+
+| Input | Failed Criteria | Why |
+|-------|-----------------|-----|
+| "Our glamping tents are the best! DM for details." | 1, 2 | No arguable claim, no concrete number |
+| "Check out our new glamping collection!" | 1, 2, 3 | Promotional, no claim, no number, no urgency |
+| "Glamping fabric tips 🧵" | 1, 2 | Topic, not claim; no number |
+
+---
+
+## Nomadixgear (DTC Consumer Gear)
+
+### Long-form PASS
+
+| Input | Result | Reason |
+|-------|--------|--------|
+| "The $400 tent that survived 3 seasons without a single patch" | PASS | Claim (outperforms), number ($400, 3 seasons), urgency (seasonal), 60 chars |
+| "Why your $800 sleeping bag fails at 30°F (and the $120 one that doesn't)" | PASS | Comparative claim, numbers ($800, $120, 30°F), urgency (winter approaching), 72 chars |
+| "The 48-hour break-in protocol that adds 3 years to tent lifespan" | PASS | Claim (protocol extends life), number (48 hours, 3 years), urgency (before season), 62 chars |
+
+### Long-form FAIL
+
+| Input | Failed Criteria | Why |
+|-------|-----------------|-----|
+| "Best camping tents for 2026" | 1, 2, 3 | Survey, no claim, no number, no urgency |
+| "How to choose a tent fabric" | 1, 2, 3 | Instructional, no claim, no number, no urgency |
+
+### Social PASS
+
+| Input | Result | Reason |
+|-------|--------|--------|
+| "3 seasons, 0 patches, 1 $400 tent. The math is brutal. 🧮 Thread:" | PASS | Claim (tent lasts), numbers (3, 0, $400), urgency relaxed, 64 chars |
+| "Stop buying $120 sleeping bags that fail at 30°F. This $800 one saves you $2,400 in replacements. 🔥" | PASS | Claim (cheap costs more), numbers ($120, 30°F, $800, $2,400), urgency relaxed, 98 chars |
+
+---
+
+## AIwithJai (Content/AI Consulting)
+
+### Long-form PASS
+
+| Input | Result | Reason |
+|-------|--------|--------|
+| "AI already outsells developers who ignore it" | PASS | Claim (AI beats humans), implied number (market data), urgency (competitive), 48 chars |
+| "The 3-degree gap that costs $7,200/month in lost bookings" | PASS | Claim (gap costs money), numbers (3-degree, $7,200), urgency (monthly loss), 56 chars |
+| "Why your content pipeline loses $50K/year to AI slop" | PASS | Claim (pipeline loses money), number ($50K/year), urgency (annual loss), 52 chars |
+
+### Long-form FAIL
+
+| Input | Failed Criteria | Why |
+|-------|-----------------|-----|
+| "AI tools for content creation" | 1, 2, 3 | Survey, no claim, no number, no urgency |
+| "Why AI is important for creators" | 1, 3 | "Why X is important" = not a claim; no urgency |
+
+### Social PASS
+
+| Input | Result | Reason |
+|-------|--------|--------|
+| "Your content pipeline loses $50K/year to AI slop. Here's the 3-step fix I gave a client last week 🧵" | PASS | Claim (pipeline loses), number ($50K), urgency relaxed, 98 chars |
+| "3-degree gap = $7,200/month lost bookings. The fix takes 2 hours. 🔥" | PASS | Claim (gap costs), numbers (3-degree, $7,200, 2 hours), urgency relaxed, 72 chars |
+
+---
+
+## Universal Weak → Sharp Patterns
+
+| Weak Topic (always FAIL) | Sharp Reframe (PASS template) |
+|--------------------------|-------------------------------|
+| "X is important" | "Why ignoring X costs $Y/month" |
+| "All about X" | "The $X mistake that Y every Z" |
+| "Why you need X" | "X beats Y because Z (data: $A vs $B)" |
+| "Guide to X" | "The $X shortcut that saves Y hours" |
+| "Best practices for X" | "The 1 rule that separates $X winners from $Y losers" |
+| "How to do X" | "Why your X fails at [metric] (and the fix)" |
+
+---
+
+## Number Detection Patterns (Criterion 2)
+
+| Pattern | Example Matches |
+|---------|-----------------|
+| Currency | $1,200, $2,800, $168,960, USD 50000, €450, £3000 |
+| Percentage | 60%, 91 percent, 41% reduction, 10x |
+| Timeframe | 18 months, 3 years, 6 months, 14 days, 48 hours |
+| Count | 6 units, 44,000 people, 3 replacements, 5x ROI |
+| Ratio | 10:1, 3:1, 60/40 split |
+
+---
+
+## Urgency Detection Patterns (Criterion 3)
+
+| Type | Example Matches |
+|------|-----------------|
+| Seasonal | "before hurricane season", "this summer", "winter approaching" |
+| Deadline | "by 2026", "Q1 deadline", "before the regulation changes" |
+| Market shift | "new competitor", "market shifting", "demand surged 91%" |
+| Competitor | "terrifies hotel chains", "disrupting the market", "first to market" |
+| Data | "new study shows", "latest data reveals", "2026 survey finds" |
+| Product | "just launched", "version 2.0", "new release" |
+
+---
+
+## Title Length Edge Cases
+
+| Title | Chars | long-form (80) | social (280) |
+|-------|-------|----------------|--------------|
+| "Why cheap glamping fabric costs more than hurricane damage" | 56 | ✅ | ✅ |
+| "The $2,800 cover that outlasts 5 cheaper replacements" | 52 | ✅ | ✅ |
+| "AI already outsells developers who ignore it" | 48 | ✅ | ✅ |
+| "Survived 3 hurricane seasons with zero patches. This $2,800 fabric isn't cheap — it's cheap to replace." | 108 | ❌ | ✅ |
+| "Your content pipeline loses $50K/year to AI slop. Here's the 3-step fix I gave a client last week" | 94 | ❌ | ✅ |
+
+---
+
+## Brand-Specific Banned Patterns (Claims Blacklist)
+
+### Enchantents (from brand-overrides.md + landscape.md)
+- "geodesic dome" / "PVDF" / "PVC" / "cotton canvas" / "yurt" / "pod"
+- "indestructible" / "hurricane-proof" / "lifetime guarantee"
+- "the best" / "perfect" / "flawless" / "ultimate"
+
+### Nomadixgear (from brand-overrides.md)
+- "military-grade" (unless spec-verified)
+- "indestructible" / "lifetime"
+- "cheapest" / "lowest price"
+
+### AIwithJai (from brand-overrides.md)
+- "guaranteed results" / "10x guaranteed"
+- "no code required" (unless literally true)
+- "replaces developers" / "fire your team"
+
+---
+
+## Test Commands
+
+```bash
+# Test long-form PASS
+sharp-thesis-validator "Why cheap glamping fabric costs more than hurricane damage" --brand enchantents --mode long-form
+
+# Test long-form FAIL
+sharp-thesis-validator "Glamping tents are durable" --brand enchantents --mode long-form
+
+# Test social PASS
+sharp-thesis-validator "Survived 3 hurricane seasons with zero patches. This $2,800 fabric isn't cheap — it's cheap to replace." --brand nomadixgear --mode social
+
+# Test social FAIL
+sharp-thesis-validator "Our glamping tents are the best! DM for details." --brand nomadixgear --mode social
+
+# Test without brand (universal only)
+sharp-thesis-validator "The 3-degree gap that costs $7,200/month in lost bookings" --mode long-form
+
+# Test with thesis-config override
+sharp-thesis-validator "Short thesis" --brand enchantents --mode long-form
+```