Topical Map Builder

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//config.yaml (tier).
2. Require brands//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.

1. 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.

1. 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.

1. 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).

1. 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.

1. 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.

1. Emit artifacts.

• brands//topical-map.json — must validate against

../../templates/topical-map.schema.json.

• A readable Markdown tree (write to brands//topical-map.md).
• Prioritised brands//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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: siddiqss
• Source: siddiqss/semantic-seo-suite
• License: MIT

Install and usage instructions live in the source repository linked above.