@lucapimenta/copy-chief-black 1.0.0

package/framework/commands/ingest.md

@@ -0,0 +1,127 @@
+---
+description: Process any source through the 7-stage Content Ingestion Pipeline (S34)
+argument-hint: "<path-or-url> (e.g., ~/Downloads/book.pdf, ~/swipes/competitor.md, https://example.com/article)"
+---
+
+# /ingest — Content Ingestion Pipeline
+
+**Input:** $ARGUMENTS
+
+Processes any source through the 7-stage Content Ingestion Pipeline (S34).
+
+## What it Does
+
+Routes the input through these 7 stages in sequence:
+
+| Stage | Name | What Happens |
+|-------|------|--------------|
+| 1 | Route | Detect source type (URL, PDF, folder, markdown) and select extractor |
+| 2 | Chunk | Smart semantic chunking with 10% overlap to preserve boundaries |
+| 3 | Canonicalize | Entity dedup via Jaccard similarity + fuzzy matching |
+| 4 | Extract | Pull insights: frameworks, claims, VOC quotes, metrics |
+| 5 | Synthesize | Append to dossier (append-only, never rewrites existing content) |
+| 6 | Cross-Reference | Link against existing knowledge in `~/.claude/knowledge/` |
+| 7 | Enrich | Suggest additions to expert profiles in `~/.claude/copy-squad/` |
+
+## Instructions
+
+When this command is invoked with `$ARGUMENTS`:
+
+### Step 1: Parse Input
+
+Extract the source path or URL from `$ARGUMENTS`.
+
+If `$ARGUMENTS` is empty, respond:
+```
+Usage: /ingest <path-or-url>
+
+Examples:
+  /ingest ~/Downloads/copywriting-book.pdf
+  /ingest ~/copywriting-ecosystem/swipes/vsl-competitor.md
+  /ingest https://example.com/article
+```
+
+### Step 2: Validate Source
+
+Check if the source exists:
+- For file paths: verify the file exists with `ls <path>`
+- For URLs: proceed (validation happens in the pipeline)
+
+If the file does not exist, report the error and stop.
+
+### Step 3: Check for Duplicate Processing
+
+```bash
+bun run ~/copywriting-ecosystem/scripts/processing-registry.ts check "$ARGUMENTS" 2>/dev/null
+```
+
+If already processed, show when it was processed and ask:
+```
+This source was already ingested on [date].
+Re-ingest? (Will append new insights only — no duplication via Jaccard dedup)
+```
+
+### Step 4: Run the Ingestion Pipeline
+
+```bash
+bun run ~/copywriting-ecosystem/scripts/content-ingestion/pipeline.ts "$ARGUMENTS"
+```
+
+Display live progress for each stage as it completes.
+
+### Step 5: Report Output
+
+After pipeline completes, report:
+
+```
+INGESTION COMPLETE: [source name]
+
+Stages completed: 7/7
+Output location: ~/.claude/knowledge/
+
+Insights extracted:
+  - Frameworks: [N]
+  - VOC quotes: [N]
+  - Claims: [N]
+  - Metrics: [N]
+
+Cross-references found: [N] existing entities matched
+
+Enrichment suggestions:
+  - [expert name]: [what was suggested]
+  - (or "None" if no enrichments)
+
+Next steps:
+  - /dossier show to inspect extracted knowledge
+  - /classify to redistribute content by offer/niche/universal
+  - /clone-expert [path] to extract full DNA from this source
+```
+
+## Output Locations
+
+| Content Type | Destination |
+|-------------|-------------|
+| Universal principles | `~/.claude/knowledge/universal/` |
+| Expert insights | `~/.claude/knowledge/experts/` |
+| VOC quotes | `~/.claude/knowledge/voc/` |
+| Entity registry | `~/.claude/knowledge/entity-registry.yaml` |
+
+## Error Handling
+
+If the pipeline fails at any stage:
+1. Report which stage failed with the error message
+2. Show what was completed before the failure
+3. Suggest: "Run with `--verbose` flag for detailed logging"
+
+## Related
+
+- `/classify` — Manually classify extracted content by offer/niche/universal
+- `/clone-expert` — Deep DNA extraction from an expert's body of work
+- `/dossier` — Manage the knowledge dossiers that ingestion populates
+- `/inbox` — Scan a drop folder and batch-ingest new files
+- `/registry` — Check processing history and avoid re-ingesting duplicates
+
+---
+
+*Sprint: S34 (Content Ingestion Pipeline) + S39 (Pipeline Commands)*
+*Script: `~/copywriting-ecosystem/scripts/content-ingestion/pipeline.ts`*

package/framework/commands/investigate.md

@@ -0,0 +1,236 @@
+---
+description: Structured investigative research mode — generates questions and identifies biases BEFORE searching
+argument-hint: "<topic> — e.g., 'CoQ10 efficacy for tinnitus', 'tinnitus avatar pain points', 'competitor VSL structure'"
+---
+
+# /investigate — Investigative Research Mode
+
+**Input:** $ARGUMENTS
+
+Structured investigation mode that generates questions and explicitly identifies biases BEFORE starting research.
+Ensures evidence is gathered for both confirming AND disconfirming hypotheses.
+
+## Why This Exists
+
+Standard research suffers from confirmation bias: we search for what confirms what we already believe.
+This protocol forces EXPLICIT bias declaration and DELIBERATE disconfirming searches before synthesis.
+
+## Instructions
+
+When this command is invoked with `$ARGUMENTS`:
+
+### Step 0: Handle Missing Input
+
+If `$ARGUMENTS` is empty:
+```
+Usage: /investigate <topic>
+
+Examples:
+  /investigate "CoQ10 efficacy for tinnitus"
+  /investigate "florayla avatar pain points"
+  /investigate "competitor VSL structure for constipation offers"
+  /investigate "shame as DRE in health niches"
+  /investigate "which hook format converts best for supplement VSLs"
+
+/investigate is for STRUCTURED research with explicit bias control.
+For VOC collection, use /audience-research-agent instead.
+```
+
+### Phase 1: Question Generation (BEFORE Any Searching)
+
+Generate 5-10 investigative questions organized by type.
+Do NOT search yet — generate questions from prior knowledge first.
+
+Display:
+```
+INVESTIGATING: "[topic]"
+
+PHASE 1 — QUESTIONS (before searching)
+
+FACTUAL (what we can measure or verify):
+  Q1. [question about verifiable data or facts]
+  Q2. [question about measurable outcomes]
+
+CAUSAL (why things happen):
+  Q3. [question about root cause or mechanism]
+  Q4. [question about what drives the outcome]
+
+COMPARATIVE (how things relate):
+  Q5. [question comparing alternatives or options]
+  Q6. [question about differences between cases]
+
+COUNTERFACTUAL (challenging assumptions):
+  Q7. What if the opposite were true?
+  Q8. What evidence would make me change my conclusion?
+
+BIAS-CHECK (making assumptions explicit):
+  Q9. What am I assuming before I even start?
+  Q10. Who benefits from the conclusion I expect to find?
+```
+
+### Phase 2: Explicit Bias Declaration
+
+Before any research, declare known biases:
+
+```
+PHASE 2 — BIAS DECLARATION
+
+Confirmation bias risks:
+  "I might look for evidence that [expected conclusion]..."
+  "I might dismiss sources that [contradict expectation]..."
+
+Availability bias:
+  "I might overweight [easily found or memorable examples]..."
+
+Authority bias:
+  "I might accept claims from [credible-sounding sources] without verifying..."
+
+Framing bias:
+  "The way I phrased '[topic]' already assumes [implicit assumption]..."
+```
+
+### Phase 3: Structured Research
+
+Now run the actual searches. For each question from Phase 1, search with BOTH confirming and disconfirming queries.
+
+For each major question, perform at minimum:
+1. A query that would find CONFIRMING evidence
+2. A query that would find CONTRADICTING evidence
+
+Tag each finding as you go:
+
+```
+PHASE 3 — RESEARCH FINDINGS
+
+Q1: [question]
+  [CONFIRMS]   — [finding + source]
+  [CONTRADICTS] — [finding + source]
+  [NEUTRAL]    — [finding + source]
+
+Q2: [question]
+  [CONFIRMS]   — [finding + source]
+  [CONFIRMS]   — [finding + source]
+  [CONTRADICTS] — [finding + source]
+
+[... continue for each question ...]
+```
+
+Finding tags:
+- `[CONFIRMS]` — Evidence that supports the main hypothesis
+- `[CONTRADICTS]` — Evidence that challenges or complicates the hypothesis
+- `[NEUTRAL]` — Evidence that neither confirms nor contradicts
+- `[UNCERTAIN]` — Finding where source reliability or relevance is unclear
+
+### Phase 4: Synthesis with Explicit Confidence Levels
+
+Present synthesized findings with explicit confidence declarations:
+
+```
+PHASE 4 — SYNTHESIS
+
+CONCLUSION: [main finding in 1-2 sentences]
+
+Supporting Evidence:
+  [FATO] [CONFIANCA: ALTA] — [claim] [FONTE: source]
+  [FATO] [CONFIANCA: MEDIA] — [claim] [FONTE: source]
+  [REC]  [CONFIANCA: MEDIA] — [inference] [justified because: ...]
+
+Contradicting Evidence:
+  [FATO] [CONFIANCA: ALTA] — [claim that complicates the conclusion]
+  Resolution: [how this was handled in the conclusion]
+
+Unresolved Questions:
+  - [question that research could not answer]
+  - [question that requires more specialized sources]
+
+CONFIDENCE IN CONCLUSION: [ALTA / MEDIA / BAIXA]
+  Justification: [why this confidence level]
+
+WHAT WOULD CHANGE THIS CONCLUSION:
+  "[specific evidence or finding that would reverse the conclusion]"
+```
+
+### Phase 5: Application to Copy Chief Workflow
+
+After synthesis, translate findings into actionable copy implications:
+
+```
+PHASE 5 — COPY IMPLICATIONS
+
+For VOC / Research:
+  [How this finding should shape VOC collection]
+
+For Briefing / HELIX:
+  [How this finding should inform MUP, MUS, or DRE selection]
+
+For Production:
+  [How this finding should shape copy angles, claims, or proof]
+
+For Validation:
+  [Claims that need blind_critic or EST validation before use]
+
+Confidence-gated recommendations:
+  If ALTA confidence: [use directly in copy with [FATO] tag]
+  If MEDIA confidence: [qualify with "evidence suggests" language]
+  If BAIXA confidence: [treat as hypothesis only, do not use as proof]
+```
+
+## Bias Tag Reference
+
+| Tag | Meaning | When to Apply |
+|-----|---------|--------------|
+| `[CONFIRMS]` | Supports hypothesis | Finding that aligns with expected conclusion |
+| `[CONTRADICTS]` | Challenges hypothesis | Finding that complicates or refutes |
+| `[NEUTRAL]` | No clear direction | Background information, context |
+| `[UNCERTAIN]` | Source or relevance unclear | Questionable source, indirect relevance |
+
+## Confidence Levels
+
+| Level | Criteria | Copy Usage |
+|-------|----------|------------|
+| ALTA | 3+ independent sources OR MCP-validated | Use directly as [FATO] |
+| MEDIA | 1-2 sources OR single validation | Qualify with "data suggests" |
+| BAIXA | Logical inference, no direct source | Hypothesis only — never use as proof |
+| NAO SEI | No data available | Do not include in copy |
+
+## Example Output (abbreviated)
+
+For `/investigate "CoQ10 efficacy for tinnitus"`:
+
+```
+PHASE 1 — QUESTIONS
+  Q1. What clinical trials exist on CoQ10 and tinnitus?
+  Q2. What dosages show effects in studies?
+  Q3. Why might CoQ10 help (mechanism)?
+  Q4. What studies show no effect?
+  Q5. What do patients report vs. what studies show?
+
+PHASE 2 — BIASES
+  Confirmation: "I might favor studies showing positive results because the offer uses CoQ10"
+  Authority: "I might accept claims from naturopathic sites without checking methodology"
+
+PHASE 3 — FINDINGS
+  [CONFIRMS]   Q1: 2019 pilot study (n=20) showed 47% improvement — PubMed 30291234
+  [CONTRADICTS] Q4: 2021 Cochrane review found insufficient evidence for any supplement
+  [NEUTRAL]    Q3: CoQ10 reduces oxidative stress in cochlear cells (mechanism plausible)
+
+PHASE 4 — SYNTHESIS
+  [FATO] [CONFIANCA: MEDIA] — CoQ10 shows promise for tinnitus in small studies
+  [FATO] [CONFIANCA: ALTA] — Larger systematic review finds insufficient evidence
+
+COPY IMPLICATION: Use mechanism (oxidative stress) as the claim, not "proven to cure".
+```
+
+## Related
+
+- `/audience-research-agent` — Full VOC extraction with Apify actors
+- `/helix-system-agent` — HELIX briefing that uses research findings
+- `/ingest` — Ingest discovered sources into the knowledge base
+- `/dossier` — Store findings as structured dossier entries
+
+---
+
+*Sprint: S39 (Pipeline Commands)*
+*Ref: `epistemic-protocol.md` — confidence levels and fact/rec tagging*
+*Ref: `voc-research.md` § VOC Quality Protocol — for avatar-specific research*
+*Ref: `debugging-hypothesis.md` — hypothesis-based approach*

package/framework/commands/merge.md

@@ -0,0 +1,35 @@
+# /merge — Semantic Merge of Parallel Outputs
+
+Merge multiple files from parallel subagent outputs, deduplicating by Jaccard similarity.
+
+## Usage
+```
+/merge <file1> <file2> [file3...]     # merge specific files
+/merge --voc-squad <offer>            # auto-merge VOC Squad outputs for an offer
+/merge --threshold 0.85               # custom Jaccard threshold (default 0.8)
+```
+
+## Steps
+
+1. Parse arguments:
+   - If `$ARGUMENTS` contains file paths → merge those files
+   - If `$ARGUMENTS` contains `--voc-squad <offer>` → find VOC analyst outputs in {offer}/research/voc/processed/
+   - Default threshold: 0.8
+
+2. Run the Semantic Merge Engine:
+   ```bash
+   bun run ~/copywriting-ecosystem/scripts/semantic-merge.ts $ARGUMENTS
+   ```
+
+3. Display merge results:
+   - Total chunks from all sources
+   - Duplicates removed (count + %)
+   - Conflicts flagged (if any)
+   - Merged output file path
+
+4. If conflicts detected, present each conflict:
+   - Source A position
+   - Source B position
+   - Ask user to resolve or mark for later
+
+Sprint: S27 — Semantic Merge Engine

package/framework/commands/next-action.md

@@ -0,0 +1,73 @@
+# /next-action — Highest-Priority Next Action
+
+Run the decision engine and recommend what to do next.
+
+## Instructions
+
+When this command is invoked:
+
+### 1. Check for Decision Engine
+If `~/.claude/scripts/decision-engine.ts` exists, run it:
+```bash
+bun run ~/.claude/scripts/decision-engine.ts 2>/dev/null
+```
+
+### 2. If Decision Engine Not Available, Manual Analysis
+If the script does not exist or fails, perform manual analysis:
+
+a) Find all offers:
+```bash
+find ~/copywriting-ecosystem -name "helix-state.yaml" -type f 2>/dev/null
+```
+
+b) For each offer, read helix-state.yaml and determine:
+   - Current phase
+   - What gate needs to pass next
+   - What deliverables are missing
+   - Mecanismo state
+
+c) Read `~/.claude/manifest.yaml` for niche ROI weights
+
+d) Score each offer using this formula:
+```
+Priority = (ROI_weight * 2) + (proximity_to_delivery * 3) + (blocked_human_gate * 5) - (effort_remaining * 1)
+```
+
+Where:
+- ROI_weight: from manifest.yaml niches section (6-9)
+- proximity_to_delivery: DELIVERED=0, PRODUCTION=3, BRIEFING=2, RESEARCH=1, IDLE=0
+- blocked_human_gate: 1 if there is a pending human gate, 0 otherwise
+- effort_remaining: estimated steps to DELIVERED (lower = higher priority)
+
+### 3. Present Results
+
+Display the TOP 3 recommendations in this format:
+
+```
+#1 [OFFER NAME] — [NICHE]
+   Phase: [CURRENT] -> Next: [NEXT STEP]
+   Action: [Specific action to take]
+   Why: [Brief rationale]
+   Command: [Suggested /command to run]
+
+#2 ...
+
+#3 ...
+```
+
+### 4. Ask for Confirmation
+
+After presenting, ask:
+> "Quer seguir com a recomendacao #1? Ou prefere outra?"
+
+If the user confirms, invoke the appropriate skill or command for that action:
+
+| Phase | Next Action | Invoke |
+|-------|-------------|--------|
+| IDLE (no research) | Start research | audience-research-agent |
+| IDLE (research done) | Start briefing | helix-system-agent |
+| RESEARCH | Continue/finish research | audience-research-agent |
+| BRIEFING | Continue HELIX phases | helix-system-agent |
+| PRODUCTION | Produce deliverables | /produce-offer [name] |
+| PRODUCTION (needs review) | Run validation | /review-all [name] |
+| Blocked human gate | Show gate details | Ask user to approve |

package/framework/commands/overnight.md

@@ -0,0 +1,177 @@
+---
+description: "Overnight autonomous production loop for multi-deliverable copy generation"
+allowed-tools: ["Bash", "Read", "Write", "Agent"]
+---
+
+# /overnight — Overnight Production Loop
+
+Triggers and manages the autonomous overnight production engine (S30). Runs all
+configured deliverables (VSL, LP, Creatives, Emails) sequentially with automatic
+halt criteria, state persistence, and morning report generation.
+
+## Subcommands
+
+| Subcommand | Action |
+|------------|--------|
+| `/overnight start <offer>` | Start overnight loop for an offer |
+| `/overnight status [offer]` | Check running or completed loop status |
+| `/overnight stop <offer>` | Gracefully stop a running loop |
+| `/overnight report <offer>` | Generate or view the morning report |
+| `/overnight help` | Show this help |
+
+---
+
+## Usage
+
+### `/overnight start <offer>`
+
+Starts the overnight production loop for the specified offer. Reads configuration
+from `~/.claude/config/overnight.yaml` and executes workflow loops for each
+configured deliverable in priority order.
+
+**What it does:**
+1. Reads overnight config (deliverables, halt criteria, max wall time)
+2. Creates state file at `{offer}/production/overnight-state/overnight-state.yaml`
+3. Executes `workflow-loops/executor.ts` for each deliverable (in Claude context: dispatches to persona subagents)
+4. Evaluates halt criteria after each iteration
+5. Generates morning report on completion
+
+**Halt criteria:**
+- Score drops 2+ iterations in a row → HALT that deliverable
+- 3 consecutive failures below threshold → HALT + flag for Conclave
+- `.overnight-stop` sentinel file detected → graceful stop
+- Max wall time (default 4h) reached → stop all
+- All deliverables passed → DONE
+
+**Examples:**
+```bash
+bun run scripts/auto-production-loop.ts start --offer florayla
+bun run scripts/auto-production-loop.ts start --offer neuvelys --config ~/my-overnight.yaml
+```
+
+---
+
+### `/overnight status [offer]`
+
+Displays current state of the overnight loop for an offer.
+
+**Shows:**
+- Loop status (running / complete / halted / stopped)
+- Per-deliverable status, final scores, iterations used, units passed
+- Runtime so far vs maximum wall time
+- Any halt reasons
+
+**Example:**
+```bash
+bun run scripts/auto-production-loop.ts status --offer florayla
+```
+
+---
+
+### `/overnight stop <offer>`
+
+Sends a graceful stop signal by creating a `.overnight-stop` sentinel file in the
+offer root. The loop halts at the next unit boundary (not mid-production).
+
+**Example:**
+```bash
+bun run scripts/auto-production-loop.ts stop --offer florayla
+```
+
+The sentinel file is automatically removed when the loop exits.
+
+---
+
+### `/overnight report <offer>`
+
+Generates or displays the morning report for the most recent overnight run.
+If a report already exists for today, reads it. Otherwise generates from state file.
+
+**Report includes:**
+- Summary: deliverables attempted, passed, stuck, halted
+- Per deliverable: chapters/blocks produced, final scores, iterations
+- Stuck items: which need human attention + Conclave commands
+- Recommendations: prioritized next actions
+- Time stats: total runtime, per-deliverable timing
+
+**Examples:**
+```bash
+bun run scripts/morning-report.ts --offer florayla
+bun run scripts/morning-report.ts --offer florayla --format json
+bun run scripts/morning-report.ts --offer florayla --date 2026-03-01
+bun run scripts/morning-report.ts --offer florayla --print
+```
+
+---
+
+## Configuration
+
+Edit `~/.claude/config/overnight.yaml` to configure:
+- Which deliverables to produce (vsl, lp, creative, email)
+- Priority order (lower number = runs first)
+- Min score threshold and max iterations per deliverable
+- Halt criteria (score drop, failure count, wall time)
+- Report output path
+
+Per-loop stop criteria and per-unit overrides are in `~/.claude/config/workflow-loops.yaml`.
+
+---
+
+## State Files
+
+| Path | Purpose |
+|------|---------|
+| `{offer}/production/overnight-state/overnight-state.yaml` | Loop state, scores, halt reasons |
+| `{offer}/.overnight-stop` | Human stop sentinel (created by `stop` command) |
+| `{offer}/production/overnight-reports/overnight-<date>.md` | Morning report (Markdown) |
+| `{offer}/production/overnight-reports/overnight-<date>.json` | Morning report (JSON) |
+
+---
+
+## Stuck Items and Conclave
+
+When a deliverable is stuck (score does not reach threshold after max iterations),
+it is flagged as `conclave_needed` in the state file. The morning report shows
+the Conclave command to run:
+
+```bash
+bun run scripts/conclave.ts \
+  --topic "Stuck Loop: vsl" \
+  --members blade,hawk,atlas \
+  --offer florayla \
+  --context "score_history: 6.5 → 7.0 → 6.8"
+```
+
+**IMPORTANT:** Conclave is NOT auto-run. Human decision required before running.
+
+Ref: `~/.claude/rules/conclave.md § S35.7` (Process Correction / Stuck Loop Detection)
+
+---
+
+## Integration
+
+| Component | Role |
+|-----------|------|
+| `scripts/auto-production-loop.ts` | Main engine (orchestrates all deliverables) |
+| `scripts/morning-report.ts` | Report generator (reads state, writes Markdown/JSON) |
+| `scripts/workflow-loops/executor.ts` | Loop engine per deliverable (S28.6) |
+| `scripts/conclave.ts` | Escalation for stuck deliverables (S35) |
+| `~/.claude/config/overnight.yaml` | Overnight configuration |
+| `~/.claude/config/workflow-loops.yaml` | Per-loop stop criteria |
+
+---
+
+## Persona Routing
+
+| Deliverable | Producer | Validator |
+|-------------|----------|-----------|
+| VSL | Echo (@vsl) | Hawk (@critic) |
+| Landing Page | Forge (@lp) | Hawk (@critic) |
+| Creatives | Scout (@creative) | Hawk (@critic) |
+| Emails | Blade (@producer) | Hawk (@critic) |
+
+Ref: `~/.claude/rules/agent-personas.md`
+
+---
+
+*S30 — Overnight Loop v2 | Copy Chief BLACK*