@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/voice-extraction/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: voice-extraction
+description: "Reverse-engineer any person's writing voice from their content. Paste in posts, articles, tweets, or essays and this skill launches 10 parallel..."
+---
+
+# /voice-extraction — Universal Voice DNA Extraction
+
+Reverse-engineer anyone's writing voice from their actual writing. Produces a structured `voice-dna.md` that lets any writer or AI replicate that voice accurately.
+
+Works with any source: files, NLM notebooks, URLs, raw text, social archives. Model-agnostic — runs on whatever model is in the session (GLM-5.1, Gemini Flash, Qwen, etc.). No Anthropic dependency.
+
+---
+
+## When to Use
+
+- "Extract my voice from these journal entries"
+- "Analyze how this person writes"
+- "Build a voice profile from my content"
+- "Match this voice" / "Make me sound like this"
+- "Study this writing and create a voice file"
+- Replacing a generic voice-profile.md with one built from real source material
+- Setting up brand voice before any content generation
+
+---
+
+## Three Modes
+
+| Mode | Input | Output |
+|------|-------|--------|
+| **extract** | Source material (any combination) | `voice-dna.md` |
+| **validate** | Content draft + `voice-dna.md` | Score (0-100) + specific fixes |
+| **inject** | `voice-dna.md` + target context | System prompt addition |
+
+---
+
+## Mode 1: Extract
+
+### Step 1: Collect Sources
+
+Gather writing samples from one or more sources. Minimum: 500 words (one article, 5+ posts, or 10+ tweets). More is better — patterns need repetition.
+
+**Source types supported:**
+
+| Source | How to Collect |
+|--------|---------------|
+| **Local files** | Glob for `.md`, `.txt` files — `--files "~/journals/*.md"` |
+| **NLM notebook** | Query via `nlm` CLI — `--nlm "<notebook-id>"` |
+| **URLs** | Fetch web pages — `--url "https://..."` |
+| **Raw text** | Paste directly — `--text "..."` |
+| **birdclaw DB** | Pull original tweets — `--birdclaw "@handle"` |
+| **Stdin** | Pipe text in — `echo "text" \| --stdin` |
+
+Use `scripts/collect-sources.sh` for automated collection:
+
+```bash
+# From local files
+bash scripts/collect-sources.sh --files "~/writing/*.md" --output corpus.txt
+
+# From NLM notebook
+bash scripts/collect-sources.sh --nlm "notebook-id-here" --output corpus.txt
+
+# Mixed sources
+bash scripts/collect-sources.sh --files "~/drafts/*.md" --url "https://blog.com/post" --output corpus.txt
+```
+
+Or collect manually — the corpus is just text. The skill doesn't require the script.
+
+### Step 2: Normalize (Optional)
+
+If the corpus has YAML frontmatter, source markers, or messy formatting:
+
+```bash
+node scripts/build-corpus.js raw-input.txt --output clean-corpus.txt
+```
+
+This strips frontmatter, normalizes whitespace, and reports word count.
+
+### Step 3: Run Extraction
+
+Load `references/extraction-prompt.md` and feed it the corpus. This is a single deep analysis pass — no multi-subagent fan-out needed. The large context windows of modern models (GLM-5.1 at 200K, Gemini Flash at 1M, Qwen at 1M) handle the full corpus in one shot.
+
+**For large corpora (50K+ words):**
+
+1. Split into sections of ~30K words each
+2. Run the extraction prompt on each section
+3. Run the synthesis prompt (in `extraction-prompt.md`) to combine the section analyses into one voice-dna.md
+
+**For small corpora (under 500 words):**
+
+Use the Quick Extraction Prompt instead — it's lighter and faster.
+
+### Step 4: Save Output
+
+Save the result following `references/voice-dna-template.md` format.
+
+**Location:**
+- If this is the canonical brand voice: `brand/voice-dna.md`
+- If extracting a specific person's voice: `brand/voices/[name].md`
+- If standalone: `./voice-dna.md`
+
+**Important:** If a `voice-profile.md` exists in the same brand directory, the new `voice-dna.md` supersedes it. Note this in the output and flag for the correction leak prevention step (grep for stale references to the old file).
+
+---
+
+## Mode 2: Validate
+
+Score content against an existing `voice-dna.md`.
+
+### Process
+
+1. Load the `voice-dna.md`
+2. Load the content draft to validate
+3. Check against the **Validation Criteria** section of the voice-dna:
+   - Count how many MUST HAVE patterns are present
+   - Count how many SHOULD HAVE patterns are present
+   - Check for any KILL FLAGS (instant fail patterns)
+4. Output:
+   - Overall score (0-100, weighted)
+   - Category breakdown
+   - Specific fixes needed (quote the voice-dna rule, show what to change)
+   - Verdict: PASS / REVISE / FAIL
+
+### Scoring
+
+```
+MUST HAVE patterns (each present = +15 pts, max 60)
+SHOULD HAVE patterns (each present = +10 pts, max 30)
+No KILL FLAGS (each kill flag = -25 pts)
+Natural feel bonus (reviewer judgment = 0-10 pts)
+
+PASS = 80+
+REVISE = 60-79
+FAIL = <60 or any KILL FLAG triggered
+```
+
+---
+
+## Mode 3: Inject
+
+Wire a `voice-dna.md` into a content generation context.
+
+### Process
+
+1. Load the `voice-dna.md`
+2. Identify the target context (a skill, a system prompt, a content brief)
+3. Extract the most relevant sections for the target:
+   - For tweets: Voice Signatures + DO/DON'T pairs + Twitter platform adaptation
+   - For blog posts: Sentence Architecture + Thematic Anchors + Blog platform adaptation
+   - For newsletters: Emotional Patterns + Newsletter platform adaptation + Thematic Anchors
+4. Format as a system prompt addition:
+
+```
+## Voice DNA (MUST FOLLOW)
+
+### Voice Signatures
+[Relevant signatures with examples]
+
+### DO / DON'T
+[Relevant pairs]
+
+### Kill Flags
+[What to never do]
+
+### Validation Checklist
+[MUST HAVE / KILL FLAGS for self-checking]
+```
+
+5. Inject into the target context
+
+---
+
+## Extraction Quality Rules
+
+### The output must be CONCRETE, not abstract
+
+| BAD (useless) | GOOD (actionable) |
+|---------------|-------------------|
+| "Confident tone" | "Uses 2-4 word fragments for emphasis: 'Four hours daily. Copying. Pasting.'" |
+| "Professional voice" | "Opens with a provocation, never a pleasantry. First sentence always makes a claim." |
+| "Engaging writing" | "Alternates between 3-word fragments and 25-word explanation sentences. The rhythm creates tension." |
+| "Authentic" | "Shares specific failures ('lost $6,500 to an agent error') before sharing wins." |
+
+### Every claim needs evidence
+
+- Every voice signature must have 2-3 verbatim quotes from the corpus
+- Every DO/DON'T pair must be based on observed patterns, not guesses
+- If the corpus doesn't show enough evidence for a section, say "Insufficient data" rather than guessing
+
+### Anti-patterns to avoid in the output
+
+- Generic personality descriptors ("confident", "professional", "authentic")
+- Advice instead of analysis ("be more specific" is advice, not a pattern)
+- Summarizing content instead of analyzing voice (WHAT they write about, not HOW)
+- Vague hedge words ("tends to", "often", "generally") — quote the text or don't claim it
+
+---
+
+## File Structure
+
+```
+voice-extraction/
+├── SKILL.md                              # This file
+├── scripts/
+│   ├── collect-sources.sh                # Multi-source text collection
+│   └── build-corpus.js                   # Normalize + combine sources
+└── references/
+    ├── extraction-prompt.md              # Master analysis prompt (core IP)
+    ├── voice-dna-template.md             # Output format specification
+    └── voice-elements.md                 # Prior extraction example (Jairo's journal)
+```
+
+---
+
+## Model Compatibility
+
+This skill is model-agnostic. It works with:
+
+- **GLM-5.1** (200K context) — handles ~30K word corpora in one pass
+- **Gemini 2.5 Flash** (1M context) — handles ~150K word corpora in one pass
+- **Qwen3 Coder** (1M context) — handles ~150K word corpora in one pass
+- **Any model with 32K+ context** — use chunked extraction for larger corpora
+
+**No Anthropic dependency.** No Claude-specific tools. No "Claude in Chrome." No multi-subagent fan-out. The extraction is a single deep analysis pass leveraging large context windows.
+
+---
+
+## Related Skills
+
+- **brand-voice** — builds voice from interview or website scrape (lighter weight)
+- **x-post-generator-openclaw** — reads voice-dna.md for tweet generation
+- **copywriting** — reads voice-dna.md for marketing copy
+- **hook-generator** — reads voice-dna.md for hook pattern matching
+- **quality-gate** — can use voice-dna validation criteria for scoring
+- **notebooklm-journal-voice** — legacy NLM-specific skill, now superseded by this skill's NLM source adapter

package/skills/voice-extraction/references/extraction-prompt.md

@@ -0,0 +1,155 @@
+# Voice DNA Extraction Prompt
+
+The master analysis prompt. This is the core IP of the skill.
+Feed it a corpus of someone's writing and it produces a structured voice-dna.md.
+
+---
+
+## How to Use
+
+1. Collect writing samples into a single corpus (see collect-sources.sh)
+2. Paste the corpus below where indicated
+3. Run the full prompt through any model with sufficient context (GLM-5.1 200K+, Gemini Flash 1M+, Qwen 1M+)
+4. The output IS the voice-dna.md — save it directly
+
+For corpora larger than the context window: split into sections, run extraction on each, then run a synthesis pass combining all section analyses into one voice-dna.md.
+
+---
+
+## The Prompt
+
+```
+You are a voice DNA analyst. Your job is to reverse-engineer a person's writing voice from their actual writing and produce a structured voice profile that lets any writer or AI replicate that voice accurately.
+
+Below is a corpus of writing by the author. Analyze it deeply and produce a Voice DNA document following the exact format specified.
+
+=== CORPUS START ===
+[CORPUS_GOES_HERE]
+=== CORPUS END ===
+
+Analyze the corpus and extract the following. Be SPECIFIC and CONCRETE — quote actual sentences from the corpus as evidence. Generic abstractions like "confident tone" or "professional voice" are useless. If you can't find an example in the text, don't claim it.
+
+## 1. VOICE SIGNATURES (3-5 patterns)
+
+The 3-5 patterns that, if removed, would make the writing sound like someone else entirely. These are the fingerprints.
+
+For each signature:
+- Name it (e.g., "Fragment Punches", "Contrast Collisions")
+- Describe the mechanical pattern (what the sentence does)
+- Give 2-3 verbatim examples from the corpus
+- Explain WHY it works (what effect it creates)
+
+## 2. SENTENCE ARCHITECTURE
+
+How this author builds sentences. Extract the actual patterns:
+
+- **Preferred lengths**: What's their default sentence length? When do they go short? When long?
+- **Opening moves**: How do they start sentences/paragraphs? (Quote 5 examples)
+- **Closing moves**: How do they end? Where does the punch land? (Quote 5 examples)
+- **Fragment usage**: Do they use incomplete sentences? How often and why? (Quote examples)
+- **List patterns**: Do they list? How? (Comma-separated, line breaks, numbered?)
+- **Transitions**: How do they connect ideas? Or do they just jump?
+
+## 3. VOCABULARY MAP
+
+- **Signature terms**: Words/phrases the author coined or uses idiosyncratically (with definitions and example usage)
+- **Reach-for words**: Words this author gravitates toward that most people wouldn't (quote with context)
+- **Banned words**: Words the author would NEVER use (infer from what they use instead)
+- **Profanity gauge**: None / occasional / frequent / signature. If used, how and why?
+- **Jargon gauge**: Do they use technical terms? Do they explain them or assume knowledge?
+
+## 4. RHETORICAL DEVICES
+
+Identify which devices this author actually uses (with examples):
+- Contrast / juxtaposition
+- Repetition / anaphora
+- Rhetorical questions
+- Direct address ("you")
+- Metaphor / analogy
+- Hyperbole
+- Understatement
+- Lists / enumeration
+- Rule of three
+- Callback / callback humor
+
+Score each device: FREQUENT / OCCASIONAL / RARE / NEVER
+
+## 5. EMOTIONAL PATTERNS
+
+- **How they express conviction**: Do they state beliefs flatly? Argue? Show through story?
+- **How they express frustration**: Direct accusation? Dry humor? Philosophical resignation?
+- **How they express excitement**: Exclamation points? Pace change? Just... more words?
+- **How they connect with the reader**: Peer-to-peer? Authority figure? Friend? Provocateur?
+- **Vulnerability level**: Do they share personal details? How deep? What do they hold back?
+
+## 6. DO / DON'T PAIRS
+
+Create 5-8 before/after pairs showing what this author WOULD write vs what they WOULD NOT write. This is the most important section for AI replication.
+
+Format:
+> DON'T (generic version): "[generic sentence any AI would write]"
+> DO (this author's version): "[how this author would say the same thing]"
+> WHY: [1 sentence explaining the difference]
+
+Base these on actual patterns observed in the corpus, not guesses.
+
+## 7. THEMATIC ANCHORS
+
+What subjects, experiences, and references does the author draw from repeatedly?
+- Core life contexts (location, occupation, family, projects)
+- Recurring metaphors or comparisons
+- Philosophical stance (in 2-3 sentences, with supporting quotes)
+- What they care about most (ranked, with evidence)
+
+## 8. PLATFORM ADAPTATIONS
+
+How does (or would) this author's voice change across platforms? For each:
+- What stays constant (the voice core)
+- What adapts (length, format, energy)
+- Example opening line for: Twitter/X, LinkedIn, Blog intro, Newsletter opening
+
+## 9. VALIDATION CRITERIA
+
+A checklist for scoring whether content matches this voice:
+- MUST HAVE (at least 2): [voice signatures that must be present]
+- SHOULD HAVE (at least 1): [secondary patterns]
+- KILL FLAGS (any of these = fail): [patterns that would immediately reveal it's NOT this author]
+
+Output the complete Voice DNA document now. Use markdown formatting with clear headers.
+```
+
+---
+
+## Synthesis Prompt (for multi-chunk corpora)
+
+When the corpus is too large for one pass, extract from each chunk separately, then synthesize:
+
+```
+Below are voice analyses extracted from different sections of one author's writing corpus.
+Synthesize them into a single unified Voice DNA document. Resolve any contradictions by
+going with the most frequently observed pattern. Merge duplicate findings. Produce the
+final document in the standard Voice DNA format.
+
+=== SECTION ANALYSES ===
+[PASTE EACH SECTION'S ANALYSIS HERE]
+=== END SECTION ANALYSES ===
+```
+
+---
+
+## Quick Extraction Prompt (for smaller corpora or time-constrained runs)
+
+```
+Analyze the writing voice in this corpus and extract:
+1. 5 signature patterns (with examples from the text)
+2. Vocabulary the author reaches for + words they avoid
+3. 5 DO/DON'T sentence pairs showing their voice vs generic writing
+4. Their default sentence rhythm and structure
+5. What makes this voice unmistakably theirs (not anyone else's)
+
+=== CORPUS ===
+[CORPUS]
+=== END ===
+
+Be concrete. Quote the text. Generic descriptors like "confident" or "professional" are banned — show the actual words.
+```

package/skills/voice-extraction/references/voice-dna-template.md

@@ -0,0 +1,168 @@
+# Voice DNA Template
+
+This is the output format for a voice-dna.md file. Every extraction should produce this structure.
+
+---
+
+## Template
+
+```markdown
+# Voice DNA: [AUTHOR NAME]
+
+> Extracted: [DATE]
+> Sources: [LIST OF SOURCES]
+> Corpus size: [WORD COUNT] words across [N] documents
+
+---
+
+## Voice Signatures
+
+### 1. [SIGNATURE NAME]
+**Pattern:** [What the sentence does mechanically]
+**Effect:** [Why it works — what feeling it creates]
+**Examples:**
+- "[verbatim quote from corpus]"
+- "[verbatim quote from corpus]"
+- "[verbatim quote from corpus]"
+
+### 2. [SIGNATURE NAME]
+[...]
+
+[Repeat for 3-5 signatures]
+
+---
+
+## Sentence Architecture
+
+**Default length:** [X-Y words typically]
+**When they go short:** [trigger/condition]
+**When they go long:** [trigger/condition]
+
+**Opening moves:**
+- "[example 1]"
+- "[example 2]"
+- "[example 3]"
+- "[example 4]"
+- "[example 5]"
+
+**Closing moves:**
+- "[example 1]"
+- "[example 2]"
+- "[example 3]"
+- "[example 4]"
+- "[example 5]"
+
+**Fragments:** [Yes/No] — [how and why, with examples]
+**Lists:** [pattern description with example]
+**Transitions:** [how they connect ideas]
+
+---
+
+## Vocabulary Map
+
+### Signature Terms
+| Term | Meaning | Example Usage |
+|------|---------|---------------|
+| "[term]" | [definition] | "[example sentence]" |
+
+### Reach-For Words
+- "[word]" — [context where they use it]
+- "[word]" — [context]
+
+### Banned Words
+- "[word]" — they use "[alternative]" instead
+- "[word]" — they use "[alternative]" instead
+
+### Profanity: [None / Occasional / Frequent / Signature]
+[Jow and why, if applicable]
+
+### Jargon: [None / Light / Heavy]
+[Do they explain terms or assume knowledge?]
+
+---
+
+## Rhetorical Devices
+
+| Device | Frequency | Example |
+|--------|-----------|---------|
+| Contrast/juxtaposition | FREQUENT | "[example]" |
+| Repetition | OCCASIONAL | "[example]" |
+| Direct address | [freq] | "[example]" |
+| [device] | [freq] | "[example]" |
+
+---
+
+## Emotional Patterns
+
+**Conviction:** [how they state beliefs, with example]
+**Frustration:** [how they express it, with example]
+**Excitement:** [how they show it, with example]
+**Reader connection:** [peer/authority/friend/provocateur — with evidence]
+**Vulnerability:** [level and what they share/hide]
+
+---
+
+## DO / DON'T Pairs
+
+> **DON'T (generic):** "[generic AI sentence]"
+> **DO (this voice):** "[how this author says it]"
+> **WHY:** [1 sentence]
+
+> **DON'T (generic):** "[generic AI sentence]"
+> **DO (this voice):** "[how this author says it]"
+> **WHY:** [1 sentence]
+
+[5-8 pairs total]
+
+---
+
+## Thematic Anchors
+
+**Core contexts:** [location, work, family, projects]
+**Recurring metaphors:** [list with examples]
+**Philosophy:** [2-3 sentences with supporting quotes]
+**What they care about (ranked):**
+1. [value] — "[evidence quote]"
+2. [value] — "[evidence quote]"
+3. [value] — "[evidence quote]"
+
+---
+
+## Platform Adaptations
+
+### Twitter/X
+**Constant:** [what never changes]
+**Adapts:** [what shifts]
+**Example opening:** "[sample line]"
+
+### LinkedIn
+**Constant:** [what never changes]
+**Adapts:** [what shifts]
+**Example opening:** "[sample line]"
+
+### Blog
+**Constant:** [what never changes]
+**Adapts:** [what shifts]
+**Example opening:** "[sample line]"
+
+### Newsletter
+**Constant:** [what never changes]
+**Adapts:** [what shifts]
+**Example opening:** "[sample line]"
+
+---
+
+## Validation Criteria
+
+**MUST HAVE (at least 2):**
+- [ ] [signature pattern 1]
+- [ ] [signature pattern 2]
+- [ ] [signature pattern 3]
+
+**SHOULD HAVE (at least 1):**
+- [ ] [secondary pattern]
+
+**KILL FLAGS (any = fail):**
+- [ ] [anti-pattern that reveals it's NOT this author]
+- [ ] [anti-pattern]
+```