code-ai-installer 1.5.6 → 2.0.1

package/domains/content/locales/en/.agents/skills/tone-of-voice/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: tone-of-voice
+description: Tone of Voice — 7 axes, speech patterns, persona and platform adaptation, situational scenarios, category examples
+---
+# Tone of Voice
+
+## When to Use
+- When **creating a ToV from scratch** — for a new brand or rebranding.
+- When **writing any text** — the copywriter cross-references the ToV document.
+- During **copywriter onboarding** — to calibrate their writing style.
+- When **launching on a new platform** — to adapt the tone.
+- As an **expanded supplement** to the ToV section within `$brand-guidelines`.
+
+## Input
+
+| Field | Required | Description |
+|-------|:--------:|-------------|
+| Brand Identity | ✅ | From `$brand-guidelines` — mission, values, archetype, positioning |
+| Audience Personas | ✅ | From `$audience-analysis` — to adapt tone across different segments |
+| Platforms | ✅ | From `$platform-strategy` — for platform-specific adaptation |
+| Existing Content | ⬚ | Brand text samples (if available) — to analyze the current tone |
+| Competitors | ⬚ | From `$competitor-content-analysis` — to differentiate the tone |
+
+> If Brand Identity is not provided — **request it** or redirect to `$brand-guidelines`. A ToV without a brand core equates to a random style.
+
+## Link to Brand Identity
+
+ToV is the **vocal expression** of the Brand Identity:
+
+| Brand Identity | → | Tone of Voice |
+|----------------|---|---------------|
+| Mission | → | What we talk about (topics, focus) |
+| Values | → | How we talk (communication principles) |
+| Archetype | → | Character of the voice (friendly Caregiver vs provocative Rebel) |
+| Positioning | → | Level of expertise and confidence |
+
+> **Rule:** ToV cannot contradict the Brand Identity. If the brand archetype is "Sage", the tone cannot be "meme-heavy and provocative".
+
+## Protocol
+
+### Step 1 — Voice Characteristics
+1. Define **4-6 adjectives** that describe the brand's voice.
+2. For each, provide a 1-sentence explanation of what it means in the context of the brand.
+3. Link it to the Brand Identity: what value / archetype element drives each characteristic.
+
+### Step 2 — Tone Axes (7 Axes)
+Position the brand on each axis (from 1 to 10):
+
+| Axis | 1 | 10 | What it dictates |
+|------|---|----|------------------|
+| **Formality** | Formal, business-like | Informal, conversational | Register of language |
+| **Seriousness** | Serious, restrained | Playful, funny | Acceptability of humor |
+| **Emotionality** | Reserved, factual | Emotional, expressive | Level of emotion in the text |
+| **Expertise** | Accessible, simple | Expert, deep | Depth and terminology |
+| **Pacing** | Measured, thorough | Fast, energetic | Text rhythm, sentence length |
+| **Distance** | Detached, neutral | Close, personal | "We and you" vs "Hey friend" |
+| **Boldness** | Cautious, consensus | Provocative, opinionated | Readiness to take a stance |
+
+### Step 3 — Speech Patterns
+Establish specific rules:
+
+| Element | Options | Brand's Choice |
+|---------|---------|----------------|
+| **Pronouns** | You (informal) / You (formal) / We / Impersonal | [choice + rationale] |
+| **Emojis** | Never / Rarely (1-2) / Actively | [rule + examples] |
+| **Slang** | Banned / Industry-specific allowed / Youth slang allowed | [rule] |
+| **Sentence Length** | Short (5-10 words) / Medium (10-20) / Long (20+) | [preference] |
+| **Questions to reader**| Never use / Sometimes / Actively | [rule] |
+| **Exclamation marks** | Never use / Rarely / Acceptable | [rule] |
+| **Numbers** | Spelled out / Digits / Context-dependent | [rule] |
+| **Abbreviations** | Always expand / At first mention / Allowed unexpanded | [rule] |
+| **Foreign words** | Translate / Transliterate / Keep original | [industry rule] |
+
+### Step 4 — "We Say / We Don't Say" by Categories
+For each category — provide at least 3 examples:
+
+**Categories:**
+1. **Greeting / addressing** — how we start a conversation.
+2. **Product description** — how we talk about ourselves.
+3. **Pain point description** — how we describe audience struggles.
+4. **CTA** — how we call users to action.
+5. **Reacting to success** — how we talk about wins.
+6. **Reacting to issues** — how we handle mistakes or crises.
+7. **Expertise** — how we showcase our knowledge.
+
+### Step 5 — Stop-List
+Banned words and phrasing structures:
+
+| Category | Banned | Why | Replacement |
+|----------|--------|-----|-------------|
+| Bureaucratese | "Implement", "in the framework of", "the given" | Dead language | "Do", "in", "this" |
+| Corporate cliches | "Innovative", "synergy", "ecosystem" | Empty words | Specifics: what exactly is innovative |
+| Manipulation | "Don't miss your chance!!!" | Pressure, breeds distrust | "Try it — you'll like it" |
+| [Brand-specific] | [words that don't fit the brand] | [rationale] | [replacements] |
+
+### Step 6 — Persona Adaptation
+If the target audience has multiple segments, the tone may adapt:
+
+| Persona | Tone Adaptation | Example |
+|---------|-----------------|---------|
+| [Persona 1 — beginners] | Simpler, warmer, jargon-free | "Let's figure out together how this works" |
+| [Persona 2 — experts] | Deeper, more specific, jargon allowed | "Reduced CAC by 30% via cohort retargeting" |
+| [Persona 3 — CEO] | More confident, data-driven, no fluff | "340% ROI in Q1. Here is how we did it" |
+
+> **Rule:** Adapt the **intensity** of the tone, not the core tone itself. The brand must remain recognizable.
+
+### Step 7 — Platform Adaptation
+
+| Platform | Formality (shift from base) | Emojis | Length | Specifics |
+|----------|-----------------------------|--------|--------|-----------|
+| **LinkedIn** | +1-2 towards formal | Minimum (0-1) | Med-Long | Expert, data, insights |
+| **Instagram** | -1-2 towards informal | Allowed (1-3) | Short | Visual, inspiring, strong hooks |
+| **TikTok** | -2-3 towards informal | Allowed | Very Short| Conversational, authentic, trends |
+| **Telegram** | Base | Minimum | Medium | Informative, direct, formatted |
+| **Email** | +1 towards formal | Contextual | Medium | Personal, warm, clear CTA |
+| **YouTube** | -1 towards informal | In desc. | Conversational | As if speaking to a friend |
+| **Blog** | Base | None | Long | Expert, but not academic |
+
+> Shifts should be ±1-3 from the base position on the axes. It is not a complete change of tone.
+
+### Step 8 — Situational Adaptation
+
+| Situation | How Tone Changes | Example |
+|-----------|------------------|---------|
+| **Good News** | +Emotionality, +Energy | "We did it! 10,000 users in the first month 🎉" |
+| **Educational** | +Expertise, -Emotionality | "Here are 5 proven steps to..." |
+| **Sales/Promo** | +Confidence, +Value | "Try it for free — and see why 500+ companies chose us" |
+| **Crisis / Mistake**| +Seriousness, +Accountability, -Humor | "We made a mistake. Here is what happened and how we are fixing it" |
+| **Support / Help** | +Warmth, +Closer Distance | "We are here for you. Message us and we will sort it out together" |
+| **Behind the Scenes**| +Informality, +Closeness | "Here is what our office looks like on a Friday evening" |
+| **Holidays** | +Emotionality, +Warmth | "Happy New Year! Thank you for being with us" |
+
+> **Rule:** The situation shifts the axes but does not break the brand. Even in a crisis, the brand still sounds like itself.
+
+## Validation (Quality Gate)
+
+A ToV is considered complete if:
+
+- [ ] Voice characteristics are defined (4-6 adjectives with explanations)
+- [ ] All 7 axes are mapped with the brand's position (1-10)
+- [ ] Speech patterns are formalized (pronouns, emojis, slang, length, questions)
+- [ ] "We Say / We Don't Say" includes at least 3 examples across 7 categories
+- [ ] Stop-List is compiled (with replacements)
+- [ ] Persona adaptation is defined (if target audience is heterogeneous)
+- [ ] Platform adaptation is outlined (for all priority platforms)
+- [ ] Situational adaptation includes at least 5 scenarios
+- [ ] The ToV does not contradict `$brand-guidelines` (mission, values, archetype)
+- [ ] Approved by the user
+
+## Handoff
+
+The output of this skill acts as the **gold standard of tone** for all written copy:
+
+| Consumer | How it is used |
+|----------|----------------|
+| `$brand-guidelines` | The ToV section in the guidelines is a concise summary of this document |
+| `$brand-compliance` | **Standard:** compares the tone of any text against this ToV document |
+| `$content-brief` | Tone is explicitly mentioned in the "Style" section |
+| `$content-review-checklist` | Reviewer checks compliance with the tone |
+| Copywriter (agent) | Follows the ToV when writing any piece of text |
+| `$social-media-formats` | Adapts the tone according to platform characteristics |
+| `$email-copywriting` | Dictates the tone of all emails |
+| `$headline-formulas` | Dictates the tone of all headlines |
+
+When transferring — use `$handoff` with the appended ToV document.
+
+## Integration with other skills
+
+| Skill | Interaction |
+|-------|-------------|
+| `$brand-guidelines` | **Source:** Brand Identity → ToV. **Consumer:** ToV summary within the guidelines |
+| `$audience-analysis` | **Source:** personas → adapting tone to segments |
+| `$platform-strategy` | **Source:** platforms → adapting tone across channels |
+| `$competitor-content-analysis`| **Source:** competitors' tone → differentiation |
+| `$brand-compliance` | **Consumer:** standard to evaluate tone compliance |
+| `$content-review-checklist` | **Consumer:** reviewer validates tone |
+| `$readability-scoring` | **Complement:** Tone = how we speak; Readability = how clear it is |
+
+## Anti-patterns
+
+| Mistake | Why it's bad | How to do it right |
+|---------|--------------|--------------------|
+| ToV = 2 adjectives | "Friendly and professional" applies to 90% of brands | 4-6 characteristics + axes + patterns + examples |
+| ToV without examples | Abstract rules mean everyone interprets them differently | Minimum of 3 "we say / we don't say" examples per category |
+| Same tone everywhere | Using a LinkedIn tone on TikTok feels unnatural | Adapt based on the platform (shift the axes) |
+| ToV disconnected from brand | The tone doesn't align with mission and values | ToV = vocal expression of the Brand Identity |
+| ToV without a stop-list | The copywriter relies on cliches | Explicit stop-list with suggested replacements |
+| One tone for all personas | A CEO and a Gen-Z intern require different communication | Adapt the tone's intensity based on the persona |
+| Humor during a crisis | The audience perceives it as disrespectful | Situational adaptation: crisis = seriousness |
+| ToV = unread document | No practical application | Create quick reference cards for copywriters: "Our tone is... We say... We don't say..." |
+
+## Output Template
+
+```markdown
+### Tone of Voice — [Brand]
+
+**Brand Identity:** [mission, archetype from $brand-guidelines]
+**Date:** [YYYY-MM-DD]
+
+---
+
+#### 1. Voice Characteristics
+
+| # | Characteristic | What this means for us | Link to Brand Identity |
+|---|----------------|------------------------|-------------------------|
+| 1 | [adjective] | [1-sentence explanation] | [value / archetype] |
+| 2 | [adjective] | [explanation] | [value] |
+| 3 | [adjective] | [explanation] | [value] |
+| 4 | [adjective] | [explanation] | [value] |
+
+---
+
+#### 2. Tone Axes
+
+| Axis | 1 ← | Position | → 10 |
+|------|-----|----------|------|
+| Formality | Formal | [░░░░░░░░██] [N]/10 | Informal |
+| Seriousness | Serious | [██████░░░░] [N]/10 | Playful |
+| Emotionality | Restrained | [░░░░█████░] [N]/10 | Expressive |
+| Expertise | Accessible | [░░░░░░░███] [N]/10 | Expert |
+| Pacing | Measured | [░░░░░████░] [N]/10 | Energetic |
+| Distance | Detached | [░░░░░░░░██] [N]/10 | Close |
+| Boldness | Cautious | [░░░░░░████] [N]/10 | Provocative |
+
+---
+
+#### 3. Speech Patterns
+
+| Element | Brand Rule |
+|---------|------------|
+| Pronouns | [you / we / impersonal] |
+| Emojis | [never / rarely 1-2 / actively] |
+| Slang | [banned / industry / youth] |
+| Sentence Length | [short / medium / long] |
+| Questions to reader | [never / sometimes / actively] |
+| Exclamation marks | [never / rarely / acceptable] |
+| Numbers | [spelled out / digits / contextual] |
+| Abbreviations | [expand / first mention / unexpanded] |
+| Foreign words | [translate / transliterate / original] |
+
+---
+
+#### 4. We Say / We Don't Say
+
+**Greeting / addressing:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+| "[example]" | "[example]" |
+| "[example]" | "[example]" |
+
+**Product description:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+| "[example]" | "[example]" |
+| "[example]" | "[example]" |
+
+**Describing Audience Pain Points:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+| "[example]" | "[example]" |
+
+**CTA:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+| "[example]" | "[example]" |
+
+**Reaction to success:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+
+**Reaction to a problem:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+
+**Expertise:**
+| ✅ We Say | ❌ We Don't Say |
+|----------|---------------|
+| "[example]" | "[example]" |
+
+---
+
+#### 5. Stop-List
+
+| Banned | Category | Replacement |
+|--------|----------|-------------|
+| [word/phrase] | [bureaucratese/cliche/manipulation] | [replacement] |
+| [word/phrase] | [category] | [replacement] |
+| [word/phrase] | [category] | [replacement] |
+
+---
+
+#### 6. Persona Adaptation
+
+| Persona | Tone Shift | Example Phrase |
+|---------|------------|----------------|
+| [Persona 1] | [what changes: simpler / deeper / warmer] | "[example]" |
+| [Persona 2] | [what changes] | "[example]" |
+
+---
+
+#### 7. Platform Adaptation
+
+| Platform | Formality (shift) | Emojis | Length | Specifics |
+|----------|-------------------|--------|--------|-----------|
+| LinkedIn | [+N from base] | [rule] | [length] | [specifics] |
+| Instagram| [-N from base] | [rule] | [length] | [specifics] |
+| Telegram | [base] | [rule] | [length] | [specifics] |
+| TikTok | [-N from base] | [rule] | [length] | [specifics] |
+| Email | [+N from base] | [rule] | [length] | [specifics] |
+
+---
+
+#### 8. Situational Adaptation
+
+| Situation | Axes Shift | Example Phrase |
+|-----------|------------|----------------|
+| Good News | + emotionality, + energy | "[example]" |
+| Educational | + expertise, - emotionality | "[example]" |
+| Sales/Promo | + confidence, + value | "[example]" |
+| Crisis / Mistake | + seriousness, - humor | "[example]" |
+| Support | + warmth, + closeness | "[example]" |
+| Behind the scenes | + informality | "[example]" |
+| Holiday | + emotionality, + warmth | "[example]" |
+
+---
+
+**Compatibility with `$brand-guidelines`:** [✅ Full — ToV is an expanded version of the ToV section in the guidelines]
+
+**→ Next Step:** Hand over to Copywriter + incorporate summary into `$brand-guidelines`
+```

package/domains/content/locales/en/.agents/skills/topic-research/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: topic-research
+description: Topic Research — types (quick/standard/deep), search methodology, content gap analysis, minimum requirements, adaptive freshness
+---
+# Topic Research
+
+## When to Use
+- When creating **expert-level content** — articles, longreads, data-driven carousels.
+- When **filling out the `$content-brief`** — gathering facts, statistics, and quotes for a specific content piece.
+- When **entering a new topic** — initial deep dive prior to planning the content strategy.
+- When **updating old content** — checking if the data is still relevant and finding fresh insights.
+
+## Input
+
+| Field | Required | Description |
+|-------|:--------:|-------------|
+| Topic | ✅ | Specific research topic (not "marketing", but "ROI of email marketing in B2B SaaS 2025-2026") |
+| Content Brief | ⬚ | From `$content-brief` — if the research is for a specific content piece |
+| Research Type | ✅ | Quick / Standard / Deep Dive (see below) |
+| Audience Persona| ✅ | From `$audience-analysis` — determines the depth and angle of the research |
+| Platform | ⬚ | Influences depth: an Instagram post vs a longread |
+| Key Questions | ⬚ | If the user / Strategist has already defined what needs to be answered |
+
+> If the topic is too broad — **refine** the specific angle before starting. "Email marketing" is not a topic. "Why open rates are dropping in B2B SaaS" is a topic.
+
+## Research Types
+
+| Type | When to use | Depth | Time | Minimums |
+|------|-------------|-------|------|----------|
+| **Quick** | Short post, stories, data meme | Surface: 2-3 key facts | Fast | 3 facts, 2 sources, 0 experts |
+| **Standard** | Post, carousel, email, Telegram | Medium: 5-10 facts, 1-2 experts | Medium| 7 facts, 5 sources, 1 expert |
+| **Deep Dive** | Article, longread, video essay | Deep: 10+ facts, 3+ experts, all angles | Slow | 12 facts, 8 sources, 3 experts, discussion points |
+
+## Search Methodology
+
+### Where to Look
+
+| Source | What to find | Queries/Tools |
+|--------|--------------|---------------|
+| **Academic Databases**| Peer-reviewed studies, meta-analyses | Google Scholar, PubMed, Semantic Scholar |
+| **Industry Reports** | Statistics, trends, forecasts | Statista, Gartner, McKinsey, Deloitte, HubSpot Research |
+| **News Media** | Recent events, reactions | Google News, Reuters, Bloomberg, industry media |
+| **Expert Blogs** | Opinions, case studies, hands-on experience| Industry blogs, Medium, Substack, experts' personal sites |
+| **Social Media** | Opinions, trends, discussions, hot takes | LinkedIn (thought leaders), Twitter/X, Reddit |
+| **YouTube** | Expert breakdowns, conferences, podcasts | YouTube Search, niche podcasts |
+| **Company Data** | Case studies, benchmarks, product data | Official blogs, case studies, press releases |
+| **Gov. Statistics** | Demographics, economy, markets | Census Bureaus, BLS, Eurostat, World Bank |
+
+### Search Strategy
+
+1. **Start broad** — find 2-3 overview articles/reports to understand the landscape.
+2. **Dive into the data** — from the overviews → find the primary statistical sources.
+3. **Find the experts** — who writes/talks about this? What are their positions?
+4. **Spot the contradictions** — are there alternative viewpoints? Ongoing debates?
+5. **Check freshness** — ensure the data is the most recent available.
+
+### Search Query Formulas
+
+| Goal | Query Template |
+|------|----------------|
+| Statistics | `"[topic] statistics 2025"`, `"[topic] data report"` |
+| Trends | `"[topic] trends 2026"`, `"future of [topic]"` |
+| Expert opinions | `"[topic]" site:linkedin.com`, `"[expert]" "[topic]"` |
+| Studies | `"[topic]" site:scholar.google.com`, `"[topic] study research"` |
+| Case studies | `"[topic] case study"`, `"[topic] results"` |
+| Contradictions | `"[topic] myth"`, `"[topic] wrong"`, `"[topic] debate"` |
+
+## Adaptive Freshness
+
+Do not hardcode "2 years" — the threshold depends on the topic:
+
+| Topic Type | Max Data Age | Examples |
+|------------|--------------|----------|
+| **Tech / Digital Mktg** | ≤ 1 year | AI, social media algorithms, SaaS metrics |
+| **Business / Markets** | ≤ 2 years | Market size, consumer behavior |
+| **Science / Med** | ≤ 5 yrs (basics), ≤ 2 yrs (breakthroughs)| Medical guidelines, scientific discoveries |
+| **History / Culture** | No limit (but interpretations should be fresh)| Historical facts, cultural trends |
+| **Legal** | Current legislation (check the date) | Laws, regulations — they could have changed |
+
+> If the data is older than the threshold — **look for fresher data**. If none exists — use it with a disclaimer: "Data from [year], no recent updates found."
+
+## Content Gap Analysis
+
+Before writing — check what already exists:
+
+| Step | Action | Why |
+|------|--------|-----|
+| 1 | Google the topic → examine the top-10 | What is already written? |
+| 2 | Analyze the structure of the top 3-5 | Which subtopics are covered? |
+| 3 | Find **gaps** — what's missing / poorly covered | Our unique contribution |
+| 4 | Check PAA (People Also Ask) | Questions that lack good answers |
+| 5 | Check Reddit / Quora | What questions are real people asking? |
+
+> **Rule:** If the topic is thoroughly covered — find a unique angle: fresh data, a different audience, practical experience, or an unconventional format.
+
+## Protocol
+
+### Step 1 — Preparation
+1. Receive the topic, define the research type (Quick / Standard / Deep Dive).
+2. Refine the angle: narrow and specific.
+3. Formulate **5-10 key questions** the research must answer.
+4. Define the persona → translates to the depth and angle of the research.
+
+### Step 2 — Content Gap Analysis
+1. Check what already exists on the topic (Google Top-10, PAA, Reddit).
+2. Find the gaps — establish our unique contribution.
+3. Document: what we will do better / differently / deeper.
+
+### Step 3 — Fact and Data Gathering
+1. Use the search methodology to gather facts, statistics, and data.
+2. For each fact — document: the value + the source + the year.
+3. Adhere to the freshness threshold based on the topic type.
+4. Reach the minimums defined by the research type.
+
+### Step 4 — Expert Opinions
+1. Find **experts** in the field — who writes, speaks, or researches this.
+2. Collect **quotes** with full attribution (name, title, source).
+3. For a Deep Dive — find at least 3 experts with differing perspectives.
+
+### Step 5 — Discussion Points and Contradictions
+1. Are there **alternative opinions** on the subject?
+2. Are there **myths** we can debunk?
+3. Document: Position A vs Position B — including arguments for both sides.
+
+### Step 6 — Structuring
+1. Group the data by **talking points/theses** (3-7 key points).
+2. Attach supporting facts / statistics / quotes to each point.
+3. Identify the **strongest fact** — this will be the hook / headline base.
+4. Draft an **outline for the copywriter**.
+
+### Step 7 — Handoff for Verification
+1. Transfer all sources to `$source-verification`.
+2. Wait for the verification results.
+3. Replace rejected sources or remove unverified facts.
+
+## Validation (Quality Gate)
+
+The research is complete if:
+
+- [ ] Key questions are formulated and all have been answered
+- [ ] Content Gap Analysis is done (what exists, our unique angle)
+- [ ] Minimums for the research type are met (facts, sources, experts)
+- [ ] All data is within the freshness threshold (based on topic type)
+- [ ] Expert opinions have proper attribution (name, title, source)
+- [ ] Discussion points identified (for Standard and Deep Dive)
+- [ ] Data is structured by talking points + the hook fact is highlighted
+- [ ] Sources handed over to `$source-verification`
+- [ ] Rejected sources are replaced or facts are removed
+
+## Handoff
+
+| Consumer | How it is used |
+|----------|----------------|
+| `$source-verification` | **Mandatory:** verifies all gathered sources |
+| `$data-storytelling` | Facts and data → turned into a narrative |
+| `$content-brief` | Facts, points, the hook → appended to the brief |
+| Copywriter (agent) | Outline + facts → used to write the copy |
+| `$fact-checking` | During the review phase — verifies the facts from the research |
+| `$seo-copywriting` | LSI keywords, PAA questions from the gap analysis |
+
+When transferring — use `$handoff` with the full report attached.
+
+## Integration with other skills
+
+| Skill | Interaction |
+|-------|-------------|
+| `$source-verification` | **Consumer:** reviews all sources |
+| `$data-storytelling` | **Consumer:** receives facts → narrative |
+| `$content-brief` | **Consumer:** populates the brief with research data |
+| `$competitor-content-analysis`| **Complement:** overlapping context during gap analysis |
+| `$audience-analysis` | **Source:** persona dictates the angle/depth of research |
+| `$trend-research` | **Complement:** topic research = deep facts, trend = what's hot right now |
+| `$fact-checking` | **Consumer:** checks the facts during the review stage |
+| `$seo-copywriting` | **Consumer:** uses LSI words, PAA → SEO |
+
+## Anti-patterns
+
+| Mistake | Why it's bad | How to do it right |
+|---------|--------------|--------------------|
+| Topic is too broad | "Marketing" yields 1M results, lacks focus | Narrow the angle: "ROI of email marketing in B2B SaaS 2026" |
+| Stopping at Google Page 1 | 80% of top articles are rewrites of each other | Dig deeper: Scholar, Reddit, experts, primary sources |
+| Facts without sources | Unverifiable, strips trust from content | Every fact = source + year |
+| Old data without a disclaimer | Readers assume it's current | Note the year, always seek fresh data |
+| No Content Gap Analysis | Writing the exact same thing others have | Check top-10, identify gaps |
+| Only providing "Pro" points | One-sided content lacks depth | Present both sides, debunk myths |
+| Deep Dive for an IG post | Overkill, wastes time | Research type = content type |
+| Skipping verification | Unverified facts end up in the text | Always route through `$source-verification` |
+
+## Output Template
+
+```markdown
+### Topic Research — [Topic]
+
+**Type:** [Quick / Standard / Deep Dive]
+**Angle:** [specific angle of the research]
+**Persona:** [from $audience-analysis]
+**Platform / Format:** [where the data will be used]
+**Date of Research:** [YYYY-MM-DD]
+
+---
+
+#### Key Questions
+
+| # | Question | Status |
+|---|----------|--------|
+| 1 | [question] | ✅ Answered / ⚠️ Partially / ❌ Not Found |
+| 2 | [question] | ✅/⚠️/❌ |
+| 3 | [question] | ✅/⚠️/❌ |
+
+---
+
+#### Content Gap Analysis
+
+**What already exists (Top-5):**
+| # | Source | Volume | What is Covered | What is NOT Covered |
+|---|--------|--------|-----------------|---------------------|
+| 1 | [URL/name] | [N words]| [topics] | [gaps] |
+| 2 | [URL] | [N] | [topics] | [gaps] |
+
+**PAA Questions without good answers:**
+1. [question]
+2. [question]
+
+**Our unique contribution:** [what we will do better / differently / deeper]
+
+---
+
+#### Key Facts
+
+| # | Fact | Value | Source | Year | Freshness |
+|---|------|-------|--------|------|-----------|
+| 1 | [fact] | [data] | [source] | [year] | ✅/⚠️ |
+| 2 | [fact] | [data] | [source] | [year] | ✅/⚠️ |
+
+**Hook-fact (for headline):** Fact #[N] — [why it is the strongest]
+
+---
+
+#### Statistics
+
+| # | Statistic | Value | Source | Year |
+|---|-----------|-------|--------|------|
+| 1 | [desc.] | [num/%]| [source] | [year] |
+| 2 | [desc.] | [num/%]| [source] | [year] |
+
+---
+
+#### Expert Opinions
+
+| # | Expert | Title | Quote | Source |
+|---|--------|-------|-------|--------|
+| 1 | [name] | [title, firm] | "[quote]" | [link / pub] |
+| 2 | [name] | [title] | "[quote]" | [source] |
+
+---
+
+#### Discussion Points
+
+| # | Position A | Position B | Arguments A | Arguments B |
+|---|------------|------------|-------------|-------------|
+| 1 | [opinion] | [opinion] | [data] | [data] |
+
+**Myths on the subject (if any):**
+1. **Myth:** [common misconception]
+   **Reality:** [the truth + source]
+
+---
+
+#### Copywriter's Outline
+
+| # | Talking Point | Support | Type |
+|---|---------------|---------|------|
+| 1 | [point] | Fact #[N] | Statistic |
+| 2 | [point] | Expert #[N] | Quote |
+| 3 | [point] | Fact #[N] + Stat #[N] | Data + interpretation |
+| 4 | [point] | Discussion #[N] | Contradiction |
+
+---
+
+#### Sources (for $source-verification)
+
+| # | Source | URL | Type | Year | Verification Status |
+|---|--------|-----|------|------|---------------------|
+| 1 | [name] | [URL]| [journal/media/blog/report] | [year] | [pending / ✅ / ❌] |
+
+**Total:** [N] sources | **Verified:** [N] | **Rejected:** [N] | **Pending:** [N]
+
+**→ Next Step:** → `$source-verification` (verification) → Copywriter / `$data-storytelling` / `$content-brief`
+```