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 <path to WORDING-GUIDE.md> --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> --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 <date>.
- 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.
1---2name: seo-reposition3description: >4 Reposition a LIVE site whose category/keyword phrasing is not ranking or is5 being mis-filed by Google/LLMs into unrelated concepts (GSC shows brand-only6 demand; category pages pull ~0 non-brand impressions). Method proven on two7 sites: SERP trap-test every candidate phrase → find the winnable wedge →8 rewording plan with a target-vs-copy rule → GUARD TESTS FIRST (red→green9 ratchet) → phased gated implementation → ship → schedule a10 predicted-vs-actual grading run. Review at the plan and PR gates is the11 owner's choice (the phase gates state the options). Trigger phrases:12 "reposition the site's SEO", "our keywords collide with X", "we're not13 ranking for our category", "Google files us under the wrong thing",14 "trap-phrase audit", "rewording plan", "find our SEO wedge".15metadata:16 source: https://skillmd.com/skills/karero/seo-reposition17---1819# SEO reposition — escape the wrong category, rank in a winnable one2021The core failure this fixes: a site's own phrasing collides with an unrelated22established concept, so Google (and LLMs) file it under the wrong thing —23"contacts" → contact lenses, "frequent flyer" → airline miles, "travel24networking app" → meet-strangers apps. No amount of on-page polish fixes a25mis-filed site; the vocabulary itself must move to winnable ground, and guard26tests must keep it there.2728Prereqs: `search-console-insights` connected (GSC data + `serp_check.py` with a29Serper key). Inputs to confirm up front: target **market, language, device** —30always pass explicit `gl`/`hl` to the SERP fetch, never rely on the helper's31defaults (a US default is wrong for a DACH-market site and vice versa).3233## Where the files go3435- `SEO-FINDINGS.md` and `SEO-CHANGELOG.md` live in the site's `docs/seo/` folder (search36 engines; beside the site's other report folders in `docs/`). Both are living files, updated in37 place. The raw SERP snapshots (public search results) go beside them in `docs/seo/`.38- A site that already has one of them in its root or in `docs/`: create the folder39 (`mkdir -p docs/seo`) and move the file there once, with `git mv` when git tracks it and `mv`40 when not, and say so. Then fix the relative links in the moved file, and the links to it from41 other files, so each still reaches its target. If more than one of the root, `docs/` and42 `docs/seo/` has a copy, move nothing and ask the owner which to keep.43- `WORDING-GUIDE.md` stays beside `POSITIONING.md` (the root, or `docs/` where the site keeps44 `POSITIONING.md` there): it is a rule document the assistant reads, not a report.45- The full Search Console export behind the diagnosis stays in the site's git-ignored46 `analytics/` folder (`search-console-insights`, `references/analytics-folder.md`); the47 findings carry only the rows their verdicts rest on. Those rows are the owner's data, so in a48 public site repo ask before committing findings that hold Search Console figures.4950## Phase 1 — Diagnose → `docs/seo/SEO-FINDINGS.md`5152- **GSC pull**: brand vs non-brand demand, per-page impressions. The tell:53 brand queries dominate and category pages get ~0 non-brand impressions.54- **SERP trap-test** (the core technique): for each candidate phrase, fetch the55 top-10 (`serp_check.py`, explicit market/lang) and read results by *intent*,56 not keyword overlap. Classify: **✅ wedge** (on-intent, no entrenched57 incumbent) · **🟠 crowded** (right category, owned by incumbents) ·58 **🚫 trap** (resolves to a different concept entirely). Keep the raw SERP59 snapshots with each verdict — graders re-check them later.60 The model assists the read; a human confirms each 🚫/🟠/✅ call.61- ≥2 rounds: replacement candidates are themselves frequently traps.62- Write `docs/seo/SEO-FINDINGS.md` from `references/seo-findings-template.md`.6364## Phase 2 — Strategy → rewording plan + `WORDING-GUIDE.md`6566- **The target-vs-copy rule** (load-bearing): a phrase can be fine as *body67 copy* but toxic as a *rank target*. Only trap-clean phrases may appear in68 title / H1 / anchor text / slug / schema / llms.txt (the "slots").69- Produce `WORDING-GUIDE.md` (`references/wording-guide-template.md`): the70 blacklist (with what Google returns instead — the *why*), approved vocabulary,71 route decisions (retarget / 301 / rename), canonical product description.72- **Gate (owner's choice — explain, then ask, don't default silently):**73 a repositioning plan can misjudge the wedge and ship confidently wrong, so74 it's a reasonable candidate for extra scrutiny — but it's still website75 content strategy, not application code, so `website-review`'s free76 two-pass audit (or `/code-review` alone) is a legitimate, sufficient77 choice on its own. If the owner wants an external second opinion on top,78 run ONE reviewer, not independent-review's own default of two:79 `independent_review.sh <path to WORDING-GUIDE.md> --plan --first-success`. State the80 tradeoff plainly (free+now vs. a few extra minutes / a credit) and let81 them pick — see `website-review`'s "Review depth" section for the full82 reasoning.8384## Phase 3 — Guard tests FIRST (red → green ratchet)8586Write failing specs from the WORDING-GUIDE before touching copy; they ratchet87green as pages land and stay as regression guards forever:8889- **trap-guard** — mechanical scan of built HTML + llms.txt + OG source for90 blacklisted phrases; source of truth = the WORDING-GUIDE blacklist, **filtered91 to `Scope: everywhere` entries only** — `slots-only` phrases are legal in body92 copy and belong to slot-guard, so scanning them here would false-fail valid93 pages. Normalize per surface (visible text, JSON-LD, anchors, llms.txt) — a94 flat regex false-positives on scripts and misses entity/casing variants.95- **slot-guard** — bans copy-legal-but-not-a-target phrases from the slots.96 Needs a per-route slot extractor (parse title/H1/JSON-LD/anchors per built97 page); **templated + hand-finished per site** — a generator can't infer the98 allowed qualifiers.99- **two-label / product-honesty guard** — where the product has two distinct100 mechanics, every matching page must name both (prevents blur-back).101- **Negative-test every guard with fixtures**: a broken sample must make the102 guard fire with its intended message — not by editing live copy. A guard that103 has never fired is a hypothesis.104105## Phase 4 — Phased, gated implementation106107- Sequence by leverage: site-wide config/footer/schema cascade first (one edit108 clears many pages) → money pages → supporting sweep (related-card anchors109 hide stale phrasing) → new comparison pages.110- Stop after each phase; show the guard burn-down (e.g. trap-guard 143→0).111 Commit per phase. Full QA via `website-qa` where available.112- **Gate (owner's choice, same as Phase 2):** `website-review` / `/code-review`113 by default; `independent_review.sh <diff> --diff --first-success` (one114 reviewer, run from the repo the diff came from: it checks the diff's base115 first) only if the owner opts in for this PR specifically. Ask, don't116 assume the heavier option.117118## Phase 5 — Ship → grade (close the loop)119120- Deploy via the repo's own deploy model; submit sitemap / IndexNow; request121 indexing for the top changed pages.122- Fill `docs/seo/SEO-CHANGELOG.md` (`references/seo-changelog-template.md`): one row per123 change — page, old→new target, expected GSC query, outcome (blank). Flip124 `planned → deployed <date>`.125- **Schedule the grading run** (~3–6 weeks out) with a concrete mechanism —126 a scheduled agent task, CI cron, or calendar entry with the exact re-check127 steps. Grading re-pulls GSC + SERP and fills the outcome column. Without this128 the changelog is a write-only log and the method never learns.129130## Boundaries131132- Delegates, never reimplements: SERP/GSC → `search-console-insights`; QA →133 `website-qa`; review gates → `website-review` by default (the site-wide134 pass; note it still assumes Claude Code — under a Codex host use the135 vendored `double-knuth` generic path instead), with `independent-review`136 as an owner-approved optional single-reviewer escalation, never its own137 two-reviewer default. Owns Phases 1–3, orchestrates 4–5.138- Never promise ranking outcomes — record predictions and grade them.