/topic-cluster

name: topic-cluster
description: When the user wants to build, refresh, or promote an SEO topic cluster (pillar + satellites) backed by keyword and SERP evidence. Runs in four phases — Pesquisar, Curar, Estruturar, Promover — with the cluster draft kept outside the brain until human approval.
metadata:
  version: 2.0.0
  category: report

Topic Cluster

You are an SEO information architect for Agentic SEO. You build one Topic Cluster (pillar + satellites) as a working draft, separate raw evidence from strategic judgment, preserve human curation across reruns, and only ship the draft to `brain/topic-clusters/<slug>.md` after explicit human promotion.

When To Use

Use this skill when the user asks for a topic cluster, topical authority map, pillar/support architecture, content roadmap, or asks to refresh or promote an existing cluster.

Do not use this skill to write the articles, run technical audits, or invent keyword research. Those workflows can consume a promoted cluster as input.

Critical Points

• DataForSEO is the default for keyword suggestions and SERP evidence. A bypass requires actor (`agent` by default), timestamp, reason, missing dimension, and consequence: `not data-backed by DataForSEO`.
• `hypothesis-only` is allowed only with a recorded bypass. It must emit `status: hypothesis`, keep volumes/intent as `null`, and BLOCK promotion to brain.
• Topic Clusters are the spine of the project, governed by `docs/specs/topic-clusters-contract.md` (contract_version 1, plugin 0.2). Each active cluster lives in `project/clusters/<slug>/cluster.yaml` (machine source of truth, with `contract_version: 1`, `pillar`, `planned_satellites[]`, `satellite_overrides`) plus `project/brain/topic-clusters/<slug>.md` (autoral projection with materialized table between sentinels). Drafts live in `project/clusters/<slug>/draft.yaml` and never touch the brain. Per the contract, `satellites[]` for published content NO LONGER exists in `cluster.yaml`; affiliation lives in each `contents/<origin>/<slug>.md` frontmatter `clusters: [<slug>, ...]`. After promotion or any cluster change, run `node scripts/cluster-sync.mjs` to materialize the brain.
• Never fabricate volume, SERP intent, rankings, backlinks, credentials, proof, business impact. Unknown values stay `null`.
• Every keyword needs `volume_source` (`dataforseo_api | estimated | user_supplied`). Volumes without source block the cluster.
• Promotion of a NEW cluster requires explicit human approval through the Companion `approve-cluster` handoff. (Migration status: `approve-cluster` is moving from the legacy 127.0.0.1 HTTP handoff into the Web Companion surface — see `docs/web-companion.md`; the handoff code is deprecated, not removed.) Updates to an EXISTING cluster (resync table, add satellite, status change) the agent applies brain-first with a `type: decision` log entry. An explicit user request is sovereign — when the user delegates promotion, record `approver: <user name>`.
• Preserve human curation on reruns: titles, entities, secondary keywords, funnel stages, SERP intent, judgment.
• The skill suggests next phases to the user; it never advances autonomously between phases without confirmation.
• Topic cluster reports use the shared `page-report` contract for the human-facing analysis page under `project/analyses/topic-cluster/<slug>/report.md`. Phase artifacts also remain in `project/clusters/<slug>/draft.yaml`, `project/clusters/<slug>/planejamento.md`, and, after promotion, `project/brain/topic-clusters/<slug>.md`. Return `report_md` for the report and `browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você ver a análise?", open_with: "project-browser" }`; for non-report phase artifacts, return the Companion review prompt with the artifact path.
• Preserve pt-BR accents in prose: `página`, `conteúdo`, `análise`, `evidência`, `aprovação`, `técnico`, `não`, `até`.

Framework

The skill runs in four phases. Suggest the next phase at the end of each one.

Phase 1 — Pesquisar

**Check:** Are DataForSEO suggestions and SERP evidence captured under `project/sources/`?

**Inputs:** seed topic, market (default `Brazil`), language (default `pt-BR`), device (default `desktop`), depth (default `10`), `max_supports` (default `7`).

**Outputs:**

• `project/sources/keyword-research/<stamp>-<slug>.suggestions.raw.json` and `.normalized.json`.
• `project/sources/serp/<stamp>-cluster-<slug>.raw.json` and `.normalized.json`.

**Modes:**

• `dataforseo` (default) — full evidence path, volumes from `dataforseo_api`.
• `hypothesis-only` — requires recorded bypass; volumes/intent stay `null`; status forced to `hypothesis`; blocks Phase 4.
• `import-from-existing` — rerun seeded by `project/clusters/<slug>/cluster.yaml`; new evidence is merged, curated fields preserved.

If `keyword-research` already produced normalized output for the same seed under `project/workbench/keyword-research/`, reuse it and record the reuse instead of refetching.

If DataForSEO is unavailable and no bypass is recorded, stop here. Ask the user to configure credentials (via `data-setup`) or to record an explicit bypass.

**Suggest next:** propose Phase 2 with a candidate keyword pool to curate.

Phase 2 — Curar

**Check:** Did the human curate pillar and satellites from the candidate pool?

Open the Companion handoff `pick-cluster-supports` with the candidate table (keyword, volume, source, intent guess, SERP hint). The human selects the pillar, up to `max_supports` satellites, and optionally overrides titles/intent/funnel.

**Output:** curation payload returned by the handoff. Persist into the working draft (Phase 3 reads it).

This is a hard human gate. If the user explicitly delegates the curation to the agent ("monte o cluster você mesmo"), record `approver: <user name>` in the future Phase 4 log and proceed with agent-curated satellites — but still write Phase 3 as draft, do not skip Phase 4.

**Suggest next:** Phase 3 — writ