topical-map-builder

name

topical-map-builder

description

Build or extend a full topical map — a pillar/cluster/supporting content architecture grounded in entity-based semantic SEO — for a brand. Use whenever the user asks for a topical map, a content plan or content strategy, keyword clustering into topics, "what should we write about", niche coverage, or how to build topical authority — even if they only mention keywords or blog ideas. Produces topical-map.json plus a readable tree and a prioritised content calendar. If the brand has no entity-profile.json, run seo-brand-foundation first. Triggers on content-planning intent broadly, not just the literal phrase "topical map".

topical-map-builder

Turn a brand's foundation into an executable content architecture: a processed topical map of pillars → clusters → supporting pages, each with an intent and a query network, split into core (monetizing) and outer (authority-feeding) sections.

Read these first: ../../framework/topical-map-theory.md, ../../framework/eav-modeling.md, ../../framework/query-semantics.md. (And 00-overview.md for provenance rules if not already this session.)

Preconditions

1. Read brands/<slug>/config.yaml (tier).
2. Require brands/<slug>/entity-profile.json. If absent, run seo-brand-foundation first — do not build a map without a foundation.

Workflow

1. Decompose the central entity (raw map). Using the entity profile's attribute inventory + eav-modeling.md, over-generate: every attribute → candidate topics; values/comparisons/how-tos → sub-topics; questions/edge-cases → supporting topics; neighbouring entities → outer topics. Completeness first; don't filter yet.

2. Apply the core/outer split from the entity profile's boundary rule. Tag each candidate core or outer. Drop anything failing the "right to cover" test (source-context.md) — respect the will-not-cover list.

3. Expand query networks per node (query-semantics.md), at the configured tier:

   • T0: reason out the network + validate a few via web_search; intent asserted.
   • T1: ../../scripts/fetch_autocomplete.py (real variants, measured), optional ../../scripts/fetch_trends.py (relative demand), and ../../scripts/serp_intent_classifier.py to upgrade intent to measured.
   • T2: ../../scripts/dataforseo_client.py for volume/difficulty/PAA (measured). Never invent search volumes.

4. Process the map: assign tier (pillar/cluster/supporting), parent, and one intent per node. Merge near-duplicates:

   • T1+: ../../scripts/cluster_keywords.py on query networks → flag & merge sibling pairs above cannibalization_threshold.
   • T0: merge by judgement (one URL, one intent).

5. Attach demand + priority. Set volume/difficulty only if grounded (tagged). Compute priority ≈ business_value × demand_signal × feasibility (topical-map-theory.md). At T0, demand is qualitative — priority_score may be asserted or left null with an ordering rationale.

6. Wire internal links (skeleton): each node's up (to parent), down (to children), and candidate lateral (siblings sharing an attribute; justify by embedding distance at T1). Full plan is linking-and-schema's job later — here just seed structure.

7. Emit artifacts.

   • brands/<slug>/topical-map.json — must validate against ../../templates/topical-map.schema.json.
   • A readable Markdown tree (write to brands/<slug>/topical-map.md).
   • Prioritised brands/<slug>/calendar.md from ../../templates/calendar.template.md.
   • T1+: render the coverage heatmap via ../../scripts/map_heatmap.py.

Definition of done (gate for P1-18)

• ≥1 pillar per defining/unique attribute of the central entity.
• Every node has tier, section, parent (except top pillars), target query, query network, and intent (with provenance).
• No sibling pair above the cannibalization threshold.
• Every outer node has a link path into the core.
• Priority order + seeded calendar exist.
• The map passes an expert sniff test: no generic filler, core/outer reflects the actual business. If it reads generic, the fix is usually in the framework docs or the entity profile, not in prompt wording.

Grounding ladder

• T0: structure + query networks by reasoning; intents/volumes asserted/absent.
• T1: autocomplete-grounded query networks, SERP-verified intents, embedding-based dedupe + lateral-link justification, relative demand.
• T2: absolute volume/difficulty + PAA from DataForSEO.