--- name: seo-reposition description: > Reposition a LIVE site whose category/keyword phrasing is not ranking or is being mis-filed by Google/LLMs into unrelated concepts (GSC shows brand-only demand; category pages pull ~0 non-brand impressions). Method proven on two sites: SERP trap-test every candidate phrase → find the winnable wedge → rewording plan with a target-vs-copy rule → GUARD TESTS FIRST (red→green ratchet) → phased gated implementation → ship → schedule a predicted-vs-actual grading run. Review at the plan and PR gates is the owner's choice (the phase gates state the options). Trigger phrases: "reposition the site's SEO", "our keywords collide with X", "we're not ranking for our category", "Google files us under the wrong thing", "trap-phrase audit", "rewording plan", "find our SEO wedge". --- # SEO reposition — escape the wrong category, rank in a winnable one The core failure this fixes: a site's own phrasing collides with an unrelated established concept, so Google (and LLMs) file it under the wrong thing — "contacts" → contact lenses, "frequent flyer" → airline miles, "travel networking app" → meet-strangers apps. No amount of on-page polish fixes a mis-filed site; the vocabulary itself must move to winnable ground, and guard tests must keep it there. Prereqs: `search-console-insights` connected (GSC data + `serp_check.py` with a Serper key). Inputs to confirm up front: target **market, language, device** — always pass explicit `gl`/`hl` to the SERP fetch, never rely on the helper's defaults (a US default is wrong for a DACH-market site and vice versa). ## Where the files go - `SEO-FINDINGS.md` and `SEO-CHANGELOG.md` live in the site's `docs/seo/` folder (search engines; beside the site's other report folders in `docs/`). Both are living files, updated in place. The raw SERP snapshots (public search results) go beside them in `docs/seo/`. - A site that already has one of them in its root or in `docs/`: create the folder (`mkdir -p docs/seo`) and move the file there once, with `git mv` when git tracks it and `mv` when not, and say so. Then fix the relative links in the moved file, and the links to it from other files, so each still reaches its target. If more than one of the root, `docs/` and `docs/seo/` has a copy, move nothing and ask the owner which to keep. - `WORDING-GUIDE.md` stays beside `POSITIONING.md` (the root, or `docs/` where the site keeps `POSITIONING.md` there): it is a rule document the assistant reads, not a report. - The full Search Console export behind the diagnosis stays in the site's git-ignored `analytics/` folder (`search-console-insights`, `references/analytics-folder.md`); the findings carry only the rows their verdicts rest on. Those rows are the owner's data, so in a public site repo ask before committing findings that hold Search Console figures. ## Phase 1 — Diagnose → `docs/seo/SEO-FINDINGS.md` - **GSC pull**: brand vs non-brand demand, per-page impressions. The tell: brand queries dominate and category pages get ~0 non-brand impressions. - **SERP trap-test** (the core technique): for each candidate phrase, fetch the top-10 (`serp_check.py`, explicit market/lang) and read results by *intent*, not keyword overlap. Classify: **✅ wedge** (on-intent, no entrenched incumbent) · **🟠 crowded** (right category, owned by incumbents) · **🚫 trap** (resolves to a different concept entirely). Keep the raw SERP snapshots with each verdict — graders re-check them later. The model assists the read; a human confirms each 🚫/🟠/✅ call. - ≥2 rounds: replacement candidates are themselves frequently traps. - Write `docs/seo/SEO-FINDINGS.md` from `references/seo-findings-template.md`. ## Phase 2 — Strategy → rewording plan + `WORDING-GUIDE.md` - **The target-vs-copy rule** (load-bearing): a phrase can be fine as *body copy* but toxic as a *rank target*. Only trap-clean phrases may appear in title / H1 / anchor text / slug / schema / llms.txt (the "slots"). - Produce `WORDING-GUIDE.md` (`references/wording-guide-template.md`): the blacklist (with what Google returns instead — the *why*), approved vocabulary, route decisions (retarget / 301 / rename), canonical product description. - **Gate (owner's choice — explain, then ask, don't default silently):** a repositioning plan can misjudge the wedge and ship confidently wrong, so it's a reasonable candidate for extra scrutiny — but it's still website content strategy, not application code, so `website-review`'s free two-pass audit (or `/code-review` alone) is a legitimate, sufficient choice on its own. If the owner wants an external second opinion on top, run ONE reviewer, not independent-review's own default of two: `independent_review.sh --plan --first-success`. State the tradeoff plainly (free+now vs. a few extra minutes / a credit) and let them pick — see `website-review`'s "Review depth" section for the full reasoning. ## Phase 3 — Guard tests FIRST (red → green ratchet) Write failing specs from the WORDING-GUIDE before touching copy; they ratchet green as pages land and stay as regression guards forever: - **trap-guard** — mechanical scan of built HTML + llms.txt + OG source for blacklisted phrases; source of truth = the WORDING-GUIDE blacklist, **filtered to `Scope: everywhere` entries only** — `slots-only` phrases are legal in body copy and belong to slot-guard, so scanning them here would false-fail valid pages. Normalize per surface (visible text, JSON-LD, anchors, llms.txt) — a flat regex false-positives on scripts and misses entity/casing variants. - **slot-guard** — bans copy-legal-but-not-a-target phrases from the slots. Needs a per-route slot extractor (parse title/H1/JSON-LD/anchors per built page); **templated + hand-finished per site** — a generator can't infer the allowed qualifiers. - **two-label / product-honesty guard** — where the product has two distinct mechanics, every matching page must name both (prevents blur-back). - **Negative-test every guard with fixtures**: a broken sample must make the guard fire with its intended message — not by editing live copy. A guard that has never fired is a hypothesis. ## Phase 4 — Phased, gated implementation - Sequence by leverage: site-wide config/footer/schema cascade first (one edit clears many pages) → money pages → supporting sweep (related-card anchors hide stale phrasing) → new comparison pages. - Stop after each phase; show the guard burn-down (e.g. trap-guard 143→0). Commit per phase. Full QA via `website-qa` where available. - **Gate (owner's choice, same as Phase 2):** `website-review` / `/code-review` by default; `independent_review.sh --diff --first-success` (one reviewer, run from the repo the diff came from: it checks the diff's base first) only if the owner opts in for this PR specifically. Ask, don't assume the heavier option. ## Phase 5 — Ship → grade (close the loop) - Deploy via the repo's own deploy model; submit sitemap / IndexNow; request indexing for the top changed pages. - Fill `docs/seo/SEO-CHANGELOG.md` (`references/seo-changelog-template.md`): one row per change — page, old→new target, expected GSC query, outcome (blank). Flip `planned → deployed `. - **Schedule the grading run** (~3–6 weeks out) with a concrete mechanism — a scheduled agent task, CI cron, or calendar entry with the exact re-check steps. Grading re-pulls GSC + SERP and fills the outcome column. Without this the changelog is a write-only log and the method never learns. ## Boundaries - Delegates, never reimplements: SERP/GSC → `search-console-insights`; QA → `website-qa`; review gates → `website-review` by default (the site-wide pass; note it still assumes Claude Code — under a Codex host use the vendored `double-knuth` generic path instead), with `independent-review` as an owner-approved optional single-reviewer escalation, never its own two-reviewer default. Owns Phases 1–3, orchestrates 4–5. - Never promise ranking outcomes — record predictions and grade them.