Content Brief Generator

---
name: content-brief-generator
description: >
  Generate entity-aware, Koray-style content briefs from a topical-map node or any
  target query — a semantically ordered heading skeleton with entity/attribute tags,
  internal-link targets, snippet target, word budgets, locked-facts references, and a
  do-not-fabricate list. Use whenever the user asks for a content brief, an article
  outline, writer instructions, "brief for X", or wants to start writing an article
  that exists in the topical map. Runs SERP recon first. Triggers on outline/brief
  intent broadly, not just the word "brief".
---

# content-brief-generator

Produce a brief a stranger writer could execute without further explanation, built on
the page's contextual vector (heading order = meaning) and locked to one macro context.

Read first: `../../framework/contextual-vectors.md`,
`../../framework/macro-micro-semantics.md`, `../../framework/query-semantics.md`,
`../../framework/internal-linking-rules.md`.

## Preconditions
- `brands/<slug>/config.yaml` (tier).
- A node in `brands/<slug>/topical-map.json` (or create an ad-hoc node from a query).

## Workflow

1. **Load the node** (target query, intent, entities, query network, internal links).
   If ad-hoc, first decompose the query's entity via `../../framework/eav-modeling.md`.

2. **SERP recon** for the target query:
   - T0: `web_search` + fetch the top 2–3 results; extract their heading structures and
     which entities/attributes they cover. Note gaps you can beat.
   - T2: `../../scripts/dataforseo_client.py` live SERP + People-Also-Ask for cleaner
     data. Record provenance.

3. **Build the contextual vector** (the outline). Order per contextual-vectors.md:
   definition/snippet lead → defining attributes → values/how-to → comparisons/related
   → question network → edge cases (macro-micro border with a grouper question). Tag
   each heading `entity:` / `attr:` / `rel:` / `q:`, state `must_cover`, set a
   `word_budget` guideline. Keep ONE macro context and one intent.

4. **Snippet target.** Write the ~40-word extractive answer the lead should win.

5. **Internal links.** Pull `up`/`down`/`lateral` from the node; add descriptive,
   varied anchor suggestions from the target nodes' query networks. Justify laterals
   (named shared attribute at T0; embedding distance at T1).

6. **Lock the facts.** List `locked_facts_refs` (keys the article may state) and an
   explicit `do_not_fabricate` list (specs/stats/prices lacking provenance — pull the
   brand's `_pending_owner_confirmation` items into here).

7. **Intent-conflict check** vs sibling nodes (query-semantics.md): flag any node with
   overlapping query network + same intent. T0 by judgement; T1 via
   `../../scripts/semantic_distance.py`.

8. **Emit** `brands/<slug>/briefs/<node-slug>.md` (a readable brief) and, if the
   pipeline wants structured data, a JSON alongside it validating against
   `../../templates/brief.schema.json`. Set node `status: briefed`.

## Definition of done
- One macro context, one intent; outline follows the contextual vector order.
- Every heading tagged + has must_cover; snippet target written.
- Internal links present with varied anchors; laterals justified.
- do_not_fabricate names the unverified brand facts explicitly.
- Intent-conflict check run; conflicts flagged or "none".

## Grounding ladder
- **T0:** LLM reasoning + web_search SERP glimpse; intent/queries `asserted`.
- **T1:** autocomplete-enriched query coverage, embedding-based conflict check + lateral
  justification, SERP-verified intent.
- **T2:** DataForSEO live SERP + PAA questions folded into the question network.