# Content Brief Creator

> Generate comprehensive content briefs through an automated 11-stage workflow combining SERP analysis, keyword research, competitor analysis, and company context. Use when creating content strategy, researching target keywords, analyzing competitors, or generating SEO-optimized content briefs from a single keyword input.

- Skill: `lcrvl2/content-brief-creator` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add lcrvl2/content-brief-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lcrvl2/content-brief-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: lcrvl2 (https://skillmd.com/u/lcrvl2)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lcrvl2/content-brief-creator

---


# Content Brief Creator

---

## MCP Tool Requirements

### Tool loading (harness-aware)

**In Claude Code**: DataForSEO and GSC tools are deferred, load them via ToolSearch before use.
**In other harnesses (e.g. Hermes)**: use the equivalent DataForSEO/GSC tools if exposed; otherwise use the documented fallbacks (the workflow MUST complete without them).

**Claude Code, at workflow start:**
```
ToolSearch: "select:mcp__dataforseo__serp_organic_live_advanced"
ToolSearch: "select:mcp__dataforseo__kw_data_google_ads_search_volume"
ToolSearch: "select:mcp__dataforseo__dataforseo_labs_google_keyword_suggestions"
ToolSearch: "select:mcp__dataforseo__dataforseo_labs_bulk_keyword_difficulty"
ToolSearch: "select:mcp__dataforseo__dataforseo_labs_search_intent"
ToolSearch: "select:mcp__dataforseo__on_page_content_parsing"
ToolSearch: "select:mcp__gsc-mcp__get_search_analytics"
ToolSearch: "select:mcp__gsc-mcp__inspect_url_enhanced"
```

**Additional for `--refresh` mode:**
```
ToolSearch: "select:mcp__crawl4ai__crawl_url"  # Crawl existing article for baseline
```

### Tool Reference Table

| Purpose | MCP Tool | Fallback |
|---------|----------|----------|
| SERP results + PAA | `mcp__dataforseo__serp_organic_live_advanced` | WebSearch |
| Keyword volume/difficulty | `mcp__dataforseo__kw_data_google_ads_search_volume` | WebSearch |
| Secondary keywords | `mcp__dataforseo__dataforseo_labs_google_keyword_suggestions` | WebSearch |
| Batch difficulty check | `mcp__dataforseo__dataforseo_labs_bulk_keyword_difficulty` | Skip |
| Automated intent classification | `mcp__dataforseo__dataforseo_labs_search_intent` | AI analysis |
| Competitor page analysis | `mcp__dataforseo__on_page_content_parsing` | WebFetch |
| Existing rankings check | `mcp__gsc-mcp__get_search_analytics` | Skip |
| URL existence check | `mcp__gsc-mcp__inspect_url_enhanced` | WebFetch |
| Content extraction | WebFetch | N/A |
| Existing article crawl (refresh mode) | `mcp__crawl4ai__crawl_url` | WebFetch |

### Fallback Strategy

The skill MUST work even when DataForSEO is completely unavailable.

```
AT WORKFLOW START:
  Attempt to load DataForSEO tools via ToolSearch

  IF DataForSEO tools load successfully:
    Use DataForSEO tools (faster, more structured data)

  ELSE (DataForSEO unavailable):
    Notify user: "DataForSEO MCP not available. Using WebSearch fallback for all data."

    Fallback mapping:
    - Stage 2a (SERP): WebSearch for "[keyword]" → extract top 10 results
    - Stage 3a (Keyword metrics): WebSearch for "[keyword] search volume" → extract estimates
    - Stage 3b (Secondary keywords): WebSearch for "keywords related to [keyword]" → extract suggestions
    - Stage 3c (Batch difficulty): SKIP (no fallback needed)
    - Stage 3d (Intent): AI analysis based on SERP composition (X blog posts = informational, etc.)
    - Stage 4a (Competitor metrics): WebFetch each URL → extract word count, headings manually
    - Stage 4b (Content deep dive): WebFetch (same as with DataForSEO)

    Workflow completes successfully with full brief.

AT WORKFLOW START (GSC):
  Attempt to load GSC tools via ToolSearch

  IF GSC unavailable:
    Notify user: "GSC not available. Skipping existing ranking check. Proceeding with new content assumption."
    Skip Stage 2b and 2c entirely
    Continue workflow
```

---

## Invocation

### Standard Mode (New Content)
```
/content-brief [keyword]
/brief [keyword]
```

### Refresh Mode (Existing Content)
```
/content-brief --refresh [url]
/brief --refresh [url]
```

Refresh mode is used for existing content that needs a full rewrite or legacy content that has no prior system context. It runs the full 11-stage workflow with these modifications:
- Stage 2c: Skips cannibalization check (URL already exists)
- Stage 2d (NEW): Crawls existing URL to extract baseline content
- Stage 5: Factors in current article performance alongside recommendations
- Stage 6: Dual info gain comparison (vs competitors AND vs current article), reuses existing slug
- Stage 10: Appends Section 7 (Refresh Context) to the brief
- Stage 11: Output filename uses `-refresh-YYYY-MM-DD` suffix

**Source**: Typically invoked by Content Refresh skill for Full Rewrite, Consolidation, or Legacy Partial Update tiers. Can also be invoked manually.

### Examples
```
/content-brief commissaire aux comptes
/brief comptabilité sci
/content-brief --refresh https://exemple.fr/blog/un-article
/brief --refresh /blog/un-article
```

### Without Keyword / URL
If invoked without a keyword, prompt the user:
> "What keyword would you like to create a content brief for?"

In refresh mode, the target keyword is extracted from the existing article (via GSC top query or crawled H1/title).

---

## Workflow (11 Stages)

### MANDATORY: Initialize Todo List at Workflow Start

**Before Stage 1**, use TodoWrite to create a task list that tracks every stage. Mark each task `in_progress` when starting it, `completed` when done. This list must be visible for the entire run.

```
TodoWrite([
  { id: "tools",   content: "Load MCP tools (DataForSEO + GSC)",                         status: "pending" },
  { id: "s1",      content: "Stage 1 — Capture target keyword",                           status: "pending" },
  { id: "s2a",     content: "Stage 2a — SERP research (top 10 results + PAA)",            status: "pending" },
  { id: "s2b",     content: "Stage 2b — Existing position check (GSC)",                   status: "pending" },
  { id: "s2c",     content: "Stage 2c — Cannibalization check [standard] / 2d Content baseline [refresh]", status: "pending" },
  { id: "s3",      content: "Stage 3 — Keyword research (volume, difficulty, secondary, intent)", status: "pending" },
  { id: "s4",      content: "Stage 4 — Competitor content analysis (5-7 URLs)",           status: "pending" },
  { id: "s5",      content: "Stage 5 — AI recommendations + user confirmation",           status: "pending" },
  { id: "s6",      content: "Stage 6 — Strategic analysis + user confirmation",           status: "pending" },
  { id: "s7",      content: "Stage 7 — Company context integration",                      status: "pending" },
  { id: "s8",      content: "Stage 8 — Competitive positioning (conditional)",            status: "pending" },
  { id: "s9",      content: "Stage 9 — Visual & resource planning",                       status: "pending" },
  { id: "s10",     content: "Stage 10 — Brief compilation + user input",                  status: "pending" },
  { id: "s11",     content: "Stage 11 — Save brief + generate article outline + summary", status: "pending" }
])
```

Update the relevant task to `in_progress` at the start of each stage, and `completed` immediately upon finishing it. For conditional stages (2c vs 2d, 8), mark the skipped one `completed` with a note in the content field if needed.

---

### Stage 1: Initial Input
**Action**: Capture target keyword from user
**User Input Required**: Target keyword only

Capture keyword and confirm: "I'll create a content brief for '[keyword]'. Let me check our existing content and gather SERP data..."

---

### Stage 2: SERP & Position Research
**Action**: Gather SERP data AND check the client's existing content/positions (if any)
**Tools**: DataForSEO + Google Search Console

#### 2a. SERP Research
**Tool**: `mcp__dataforseo__serp_organic_live_advanced`

**Data to Gather**:
- Top 10 SERP results (URLs, titles, meta descriptions)
- SERP features present (Featured Snippet, PAA, Video, etc.)
- PAA questions (extracted from SERP)
- Competitor URLs for further analysis

**Note**: See [data-gathering-workflow.md](references/data-gathering-workflow.md) for API parameters.

#### 2b. Existing Position Check
**Tool**: `mcp__gsc-mcp__get_search_analytics`

**Check**:
- Does the client's site already rank for this keyword?
- What position? What page?
- What's the current click-through rate?

**Note**: See [data-gathering-workflow.md](references/data-gathering-workflow.md) for API parameters.

#### 2c. Content Cannibalization Check

**In `--refresh` mode**: Skip this check entirely. We already know the URL exists — that's the point.

**In standard mode**: Check if we're about to cannibalize existing content.

**Cannibalization Threshold**: Flag if EITHER condition is met:
1. Existing page ranks **position 1-10** for the exact keyword
2. Existing slug **matches the keyword pattern**

If flagged, present options:
1. Create **NEW CONTENT BRIEF** (different angle)
2. **Abort**
3. **Switch to refresh mode** for this URL → restarts workflow as `/content-brief --refresh [existing-url]`

Wait for user decision.

If position >10 and slug doesn't match, note in brief and continue.

**See**: [data-gathering-workflow.md](references/data-gathering-workflow.md) for complete logic.

**Output**: SERP data, existing ranking status, decision (if flagged)

#### 2d. Existing Content Baseline (Refresh Mode Only)

**Condition**: Only runs in `--refresh` mode.

**Tool**: `mcp__crawl4ai__crawl_url` (fallback: WebFetch)

**Actions**:
1. Crawl the existing URL
2. Extract baseline data:
   - Current H1, H2/H3 structure
   - Word count
   - Existing internal/external links
   - Existing CTAs
   - Content sections and coverage
   - Publication date / last modified date
3. Query GSC for the URL's top queries, position, clicks, impressions
4. Store as `existing_content` context for later stages

**Output**: Existing content baseline (structure, metrics, content map)

---

### Stage 3: Keyword Research
**Action**: Gather keyword metrics, related terms, and validate viability
**Tools**: DataForSEO Keywords + Labs

#### 3a. Primary Keyword Metrics
**Tool**: `mcp__dataforseo__kw_data_google_ads_search_volume`

**Data to Gather**:
- Search volume (monthly)
- Keyword difficulty
- CPC (cost-per-click)
- Competition level

#### 3b. Secondary Keywords & Suggestions
**Tool**: `mcp__dataforseo__dataforseo_labs_google_keyword_suggestions`

**Data to Gather**:
- Related keywords (10-15)
- Long-tail variations
- Question-based keywords

#### 3c. Batch Difficulty Check
**Tool**: `mcp__dataforseo__dataforseo_labs_bulk_keyword_difficulty`

**Action**: Check difficulty for all secondary keywords at once.

#### 3d. Automated Intent Classification
**Tool**: `mcp__dataforseo__dataforseo_labs_search_intent`

**Action**: Get automated intent classification as starting point for AI analysis.

#### 3e. Keyword Viability Warnings
**Important**: These are informational warnings, NOT blockers. Low-volume and high-difficulty keywords can still be valuable.

Display warnings for low volume (<100/month), high difficulty (>70), or intent mismatches. Workflow continues automatically after displaying warnings. Warnings are logged in brief metadata.

**Output**: Keyword metrics, secondary keywords with difficulty, intent classification, warnings noted in brief metadata

---

### Stage 4: Competitor Content Analysis
**Action**: Deep analysis of top 5-7 competitor articles
**Tools**: DataForSEO On-Page + WebFetch

**IMPORTANT**: This stage happens BEFORE AI recommendations so analysis is informed by actual competitor data.

#### 4a. Competitor Metrics
Use `mcp__dataforseo__on_page_content_parsing` to extract: word count, page structure (H1/H2/H3), meta title/description, link counts.

#### 4b. Content Deep Dive
Use WebFetch for each competitor to analyze: H2 outline, unique angle, visual elements, E-E-A-T signals, CTAs, strengths, weaknesses.

#### 4c. Create Competitor Matrix
Document all findings in a comparison table. Identify: common themes, content gaps (information gain opportunities), average word count, visual gaps.

**Full methodology**: [serp-analysis-methodology.md](references/serp-analysis-methodology.md)

**Output**: Competitor analysis matrix with gaps identified

---

### Stage 5: AI Analysis & Recommendations
**Action**: Analyze ALL data and generate recommendations
**User Confirmation Required**: Yes

**Now informed by**: SERP data, keyword metrics, intent classification, AND competitor analysis.

**In `--refresh` mode**: Also informed by existing content baseline (Stage 2d). Factor in current article's performance — what's working (keep), what's declining (fix), and what's missing (add). Recommendations should preserve high-performing sections while addressing decay signals.

#### AI Determines:

**1. Search Intent — Micro-Intent Analysis** (enhanced by DataForSEO + competitor analysis + SERP title analysis)

The classic 4-intent classification (informational, commercial, transactional, navigational) is a starting point but insufficient for content decisions. Go deeper with **micro-intents** and **sub-intent detection**.

**Step 1 — Classic classification (baseline)**:
- DataForSEO intent classification: [result]

**Step 2 — SERP title-by-title analysis (critical)**:
Analyze each top 10 result's title and classify it by page type (listicle, landing page, definition, how-to, comparison, product page, etc.). Group results by type to identify **sub-intents** — a single SERP often serves multiple distinct user questions.

Example: "agence GEO" contains two sub-intents:
- Sub-intent A (~30% of results): "Quelle est la meilleure agence GEO ?" → Top 10/listicle
- Sub-intent B (~70% of results): "Je cherche une agence GEO" → Landing page service

**Step 3 — Micro-intent classification**:
Classify the primary sub-intent using these micro-intents:

| Parent Intent | Micro-Intent | User Expects | Typical Content Type |
|---|---|---|---|
| Informational | **Entertainment** | Snackable, viral content | Memes, short videos, social |
| Informational | **Definition** | Basic "What is..." answer | Wikipedia-style, featured snippet |
| Informational | **Expansional** | Deep, multi-perspective coverage | Pillar pages, comprehensive guides |
| Informational | **Enablement** | Step-by-step "How do I..." guidance | How-to guides, tutorials |
| Informational | **Aggregation/Overview** | Concise neutral overview | Tables, listicles, summaries |
| Transactional | **Comparison/Orientation** | Best solution overview | Ranked listicles, tests, comparisons |
| Transactional | **Category/Selection** | Product group overview | Category pages, service overviews |
| Transactional | **Service/Product** | Detailed specs, price, delivery | Product/service detail pages |
| Transactional | **Brand** | Trust signals about a provider | Testimonials, case studies, reviews |
| Navigational | **Support** | Help using a product | FAQs, instructions, product guides |
| Navigational | **Location** | Find a physical place | Maps, local listings |
| Navigational | **Website** | Navigate to a specific site section | Direct navigation |

**Step 4 — Sub-intent validation**:
Test derived queries to confirm sub-intent clusters exist separately:
- "meilleur [keyword]", "best [keyword]" → comparison cluster
- "qu'est-ce que [keyword]", "what is [keyword]" → definition cluster
- "[keyword] prix/pricing" → service/product cluster
If derived queries produce a distinctly different SERP composition, the sub-intents are confirmed as separate clusters.

**Step 5 — Provide multiple response formats**:
When the identified micro-intent supports featured snippets, plan multiple content formats (table + ordered list + detailed paragraphs) so Google can select the optimal snippet format.

**Output**:
- SERP composition analysis: [X blog posts, Y product pages, Z listicles]
- Sub-intents detected: [list with estimated SERP share %]
- Primary micro-intent: [micro-intent name]
- Secondary micro-intent (if any): [micro-intent name]
- **Final Recommendation**: [Informational / Commercial / Transactional] + micro-intent + recommended content angle

**2. Content Type**
Based on competitor analysis:
- What format dominates SERP? [format]
- Average word count: [X words]
- **Recommendation**: [Content type] ([word count range])

**3. Product Approach**
- Does keyword include brand/competitor names?
- Are competitors promotional or educational?
- **Recommendation**: [Product-focused / Product-mentioned / Agnostic]

**4. Target Persona**
Match to audiences-personas.md based on:
- Keyword intent and complexity
- Company size indicators
- Role-specific terms

**5. Content Cluster**
Match to `linking-clusters.md` (client context) for internal linking strategy.

#### Present to User:
Present search intent, content type (with word count), product approach, target persona, and content cluster with brief rationales. Ask: "Do these recommendations look correct, or would you like to adjust any?"

**Wait for user confirmation or adjustments before proceeding.**

---

### Stage 6: AI Strategic Analysis
**Action**: Generate strategic recommendations based on competitor gaps
**User Confirmation Required**: Yes

#### AI Determines:

**1. Information Gain Opportunities** - Split into TWO categories:

**A. Article Info Gain (3-5 items)** - Executable by Article Creator
Examples: comprehensive coverage, unique angles, expert quotes, comparison tables, case studies, proof points, step-by-step breakdowns.

**In `--refresh` mode**: Dual comparison — identify gaps vs competitors AND vs the current article. Categorize each opportunity as:
- **NEW**: Not in current article or competitors
- **UPGRADE**: In current article but competitors do it better
- **KEEP**: Current article already covers this well

**B. Supporting Assets (0-3 items)** - Requires separate development
Examples: downloadable templates, interactive tools, PDF lead magnets, custom infographics, video content.

**Reference**: [information-gain-framework.md](references/information-gain-framework.md)

**2. Narrative Frame** - Define the unique hook that differentiates from competitors.

**3. Think-Feel-Do** - Map reader journey: belief change (Think), emotional driver (Feel), desired action (Do).

**4. CTA Selection** - The client's primary CTA from `guidelines-donts.md`, with aggressiveness matched to content type and awareness stage. Without client context: neutral CTA, never an invented offer.

**5. Awareness Stage** - Determine TOFU/MOFU/BOFU based on intent.

**6. Slug Generation + Check** - In standard mode: generate slug, verify availability using `mcp__gsc-mcp__inspect_url_enhanced`. If exists, suggest alternatives and confirm with user. **In `--refresh` mode**: Reuse the existing URL slug (no generation or availability check needed).

#### Present to User:
Present article info gain (3-5 items with rationale), supporting assets (0-3 items), narrative frame, Think-Feel-Do framework, recommended CTA, awareness stage, and verified slug. Ask: "Do these recommendations look good, or would you like to adjust any?"

**Wait for user confirmation or adjustments before proceeding.**

---

### Stage 7: Company Context Integration (OPTIONNEL — sauté si pas de contexte)
**Action**: Si un contexte client existe, le charger pour caler le contenu sur la voix/positionnement du client. **Sinon, sauter entièrement cette étape** et produire un brief neutre (basé sur SERP + mot-clé). Aucune société n'est codée en dur.
**Automated**: No user input required

**Où chercher le contexte (dans cet ordre)** :
1. Si un slug client est fourni : `seo/clients/<slug>/context/`
2. Sinon, aucun contexte → brief générique.

**RÈGLE** : ne charger un fichier QUE s'il existe ET qu'il est rempli (un fichier-template
contenant « À remplir pour ce client » compte comme VIDE → ignorer). Si tout est vide/absent,
ne charge rien et continue : le brief s'appuie alors uniquement sur l'analyse SERP et le mot-clé.
Ne JAMAIS injecter de marque, produit, persona ou CTA qui ne viendrait pas d'un fichier de
contexte réellement rempli. (Historique : ce skill chargeait un KB client codé en dur —
supprimé. Le contenu n'est spécifique que si le client a fourni son contexte.)

| File (si présent & rempli) | What to Extract |
|------|-----------------|
| `brand-voice.md` | Ton de référence pour le writer |
| `vocabulary.md` | Terminologie à employer (+ NAP/identité légale) |
| `product-value.md` | Offre/services, cas d'usage, priorités commerciales |
| `audiences-personas.md` | Pain points de la cible, persona négatif |
| `proof-points.md` | Métriques, preuves ET cas clients/citations (rôle customer-stories fusionné) |
| `positioning-messages.md` | Positionnement, différenciateurs ET présentation entreprise (rôle company-overview fusionné) |
| `guidelines-donts.md` | Garde-fous éditoriaux et réglementaires à répercuter dans le brief |
| `linking-clusters.md` | Clusters, money pages cibles, règles de maillage interne |

(Standard 8 fichiers, 2026-07. Les anciens noms `customer-stories.md`, `company-overview.md`,
`competitive-landscape.md`, `technical-architecture.md` peuvent exister sur de vieux clients :
les charger s'ils sont présents et remplis, mais ne pas les attendre.)

**Output**: Contexte client (si disponible) prêt pour la compilation — sinon brief neutre.

---

### Stage 8: Competitive Positioning (Conditional)
**Action**: Load competitive landscape data
**Condition**: Only if content is product-focused or comparison

```
IF content_approach == "product-focused" OR
   content_type == "comparison" OR
   keyword contains competitor name:

  Load competitive-landscape.md (si présent dans le contexte client)
  Sinon, utiliser la section positionnement concurrentiel de positioning-messages.md
  (standard 8 fichiers : pas de fichier competitive dédié par défaut)
  Identify the client's advantages vs competitors in SERP (uniquement si le contexte le fournit)
  Add competitive angles to information gain opportunities

ELSE:
  Skip this stage
```

**Output**: Competitive advantages to highlight (if applicable)

---

### Stage 9: Visual & Resource Planning
**Action**: Generate visual recommendations based on competitor audit
**User Input Required**: Yes (for existing assets)

Generate 5-7 specific visual recommendations based on: competitor visual gaps, complex topics needing diagrams, data needing charts, comparison opportunities.

Ask user: "Do you have any existing videos, social media posts, or other assets we should embed or reference in this content? (Enter URLs or 'none')"

**Output**: Visual ideas list + existing assets (if provided)

---

### Stage 10: Brief Compilation
**Action**: Compile all gathered data into complete brief
**User Input Required**: Yes (for remaining fields)

**Template**: [content-brief-template.md](assets/templates/content-brief-template.md)

#### Ask User for Missing Fields:
**Si un contexte client est chargé (Stage 7), dériver ces champs du contexte au lieu de les demander** :
1) Content objective ← CTA principal de `guidelines-donts.md`
2) Byline ← règle de signature de `guidelines-donts.md` (section E-E-A-T)
3) Perspective ← personne et adresse de `brand-voice.md`

Ne demander à l'utilisateur QUE les champs introuvables dans le contexte. Sans contexte client : demander les 3 (objective, byline, perspective).

#### Compile Brief:
Fill all sections of content-brief-template.md:
- Section 1: Basic Infos (format, perspective, objective)
- Section 2: Strategy (cluster, intent, information gain, narrative, CTA)
- Section 3: Target Audience (persona, pain points, awareness stage)
- Section 4: SEO (keywords, SERP, competitors, titles, meta, PAA)
- Section 5: Resources (product info, brand voice, assets)
- Section 6: Linking (internal links, external links, forbidden sites)

**In `--refresh` mode**, also append:
- **Section 7: Refresh Context**
  - Current URL and publication date
  - Baseline metrics (position, clicks, impressions, CTR from GSC)
  - Decay signals that triggered the refresh (from Content Refresh skill)
  - Refresh tier and legacy status
  - Current article structure summary (from Stage 2d crawl)
  - Specific sections to keep, update, or remove (based on Stage 6 analysis)
  - Success criteria (measurable targets for position, traffic, CTR recovery)

#### Validate Completeness:
```
Check all required fields are populated:
- [ ] All 6 sections complete
- [ ] 3-5 information gain opportunities (specific, not vague)
- [ ] 5 title ideas generated
- [ ] Meta description under 160 characters
- [ ] Internal links include pillar + 3-5 related pages
- [ ] External link suggestions included
- [ ] CTA placed appropriately
- [ ] Visual ideas specific and actionable
```

**Output**: Complete content brief (markdown format)

---

### Stage 11: Output & Review
**Action**: Save brief, generate writer summary, and present to user

#### Save Full Brief:
```
Standard mode:
  Filename: content-brief-[keyword-slug]-[YYYY-MM-DD].md

Refresh mode:
  Filename: content-brief-[keyword-slug]-refresh-[YYYY-MM-DD].md

Location: Content-brief-creator/generated-briefs/
```

**Note**: The `generated-briefs/` folder is for production briefs. Test briefs go in `test-briefs/`.

#### Generate Article Outline:
Create an Article Outline section at the end of the brief. This is the most actionable deliverable - a structured H2/H3 outline based on competitor analysis, PAA questions, and information gain opportunities.

```markdown
## Article Outline

1. **H2: [Section 1]**
   - **H3: [Subsection 1a]**
     - Key points to cover
   - **H3: [Subsection 1b]**
     - Key points to cover

2. **H2: [Section 2]**
   - **H3: [Subsection 2a]**
     - Key points to cover
   - **H3: [Subsection 2b]**
     - Key points to cover

3. **H2: [Section 3]**
   - **H3: [Subsection 3a]**
     - Key points to cover

[Continue for all H2 sections - typically 5-8 H2s with 1-3 H3s each]
```

**The Article Outline is MANDATORY**. Include H3 subheadings where content warrants subdivision. Base structure on competitor H2/H3 patterns + identified gaps. All other information (keyword, persona, CTAs, proof points, etc.) is already in the main brief sections above.

#### Present Summary to User:
Display success message with: target keyword (volume, difficulty), content type, persona, cluster, key findings (current ranking, top competitors, avg word count, SERP features), top 3 info gain opportunities, deliverable file paths, and recommended next steps checklist.

---

## Error Handling

### DataForSEO Unavailable
```
"DataForSEO MCP not available. Falling back to WebSearch.
This will take longer but will provide complete results."
```

### GSC Unavailable
```
"Google Search Console MCP not available.
Skipping existing ranking check. Proceeding with new content assumption.
Recommend manually checking for existing content on this topic."
```

### Competitor Content Behind Paywall
```
"[URL] is behind a paywall. Skipping and analyzing next-highest ranking URL."
```

### Insufficient SERP Results
```
"Found only [X] results for this keyword. This may indicate:
- Very niche/specific topic
- New/emerging keyword
- Typo in keyword

Would you like to proceed with [X] competitors, or try a different keyword?"
```

### Keyword Viability Warnings
Informational warnings only - workflow continues automatically. Warnings logged in brief metadata.

### Slug Already Exists
In standard mode: Propose alternatives (e.g., [slug]-guide, [slug]-2026) or ask for custom slug.
In refresh mode: Expected behavior — reuse existing slug.

### Existing URL Not Crawlable (Refresh Mode)
```
"Cannot crawl [URL]. The page may be behind a paywall, require authentication,
or return an error. Proceeding with GSC data only for baseline metrics.
Content structure will be inferred from SERP cache if available."
```

### KB File Not Found
Notify user and proceed without that data type. Suggest creating file for future briefs.

---

## User Interaction Points

### Required User Input (4-5 Total)
1. **Stage 1**: Target keyword (standard mode) or target URL (refresh mode)
2. **Stage 2c**: Cannibalization decision (standard mode only — ONLY if position 1-10 AND slug matches, includes "switch to refresh mode" option)
3. **Stage 5**: Confirm/override AI recommendations (content type, persona, etc.)
4. **Stage 6**: Confirm/override strategic recommendations (information gain, CTA, etc.)
5. **Stage 10**: Content objective, byline, perspective

### Optional User Input
1. **Stage 6**: Slug alternative (if proposed slug exists)
2. **Stage 9**: Existing videos/social posts to embed
3. **Any Stage**: Override any AI recommendation

### Informational Only (No User Input Required)
1. **Stage 3e**: Viability warnings displayed but workflow continues automatically

---

## Reference Files

**Detailed Methodology:**
- [references/serp-analysis-methodology.md](references/serp-analysis-methodology.md) - Competitor analysis methodology
- [references/data-gathering-workflow.md](references/data-gathering-workflow.md) - Operational workflow + API parameters
- [references/information-gain-framework.md](references/information-gain-framework.md) - Information gain identification
- [references/brief-structure-guide.md](references/brief-structure-guide.md) - Section explanations

**Templates:**
- [assets/templates/content-brief-template.md](assets/templates/content-brief-template.md) - Fillable brief template

**Test Cases:**
- [test-briefs/](test-briefs/) - Sample briefs for informational, comparison, and how-to content

**Version History:**
- [CHANGELOG.md](CHANGELOG.md) - Complete version history