# SEO Audit Methodology — Handover Document

**Playbook release: `2026-11-06.1`** — [verify the live release](https://seo-audit-site.vercel.app/handover/release.json).
**Purpose:** Reusable guide for running a full SEO audit with Claude on a new client website.

**Skills used:** Squirrel Scan, `BigChrisCooke/seo-playbook-skills`, and the remaining analysis skills from `coreyhaines31/marketingskills`. Invoked via `/skill-name` slash commands in Claude Code.

## Install the playbook skills

These five skills are public on [GitHub](https://github.com/BigChrisCooke/seo-playbook-skills) and install through the [skills CLI](https://skills.sh/docs):

```bash
npx skills add BigChrisCooke/seo-playbook-skills --skill remove-ai-slop-without-removing-ctas-and-good-marketing-copy trend-scan claim-check ai-seo-better-than-corey-haines schema-markup-better-than-corey-haines
```

Select your agent in the installer (Claude Code, Cursor, or Codex). Installation is project-local by default; add `--global` for all projects. Requires Node.js/npm for installation and Python 3.10+ for the helpers; no pip packages or API keys are needed for these three scripts. Restart the agent session if the skills are not yet visible.

| Skill | What it contributes | When the audit uses it |
| --- | --- | --- |
| [Remove AI slop without removing CTAs and good marketing copy](https://skills.sh/BigChrisCooke/seo-playbook-skills/remove-ai-slop-without-removing-ctas-and-good-marketing-copy) | Humanize AI-written SEO blogs and marketing copy while preserving calls to action, product links, offers, brand voice, positioning, and proof. Includes a conversion guard and prose rubric. | [Phase 2](https://seo-audit-site.vercel.app/methodology/phase-2-skills), when kickoff confirms AI-written pages. Work on audit copies. |
| [trend-scan](https://skills.sh/BigChrisCooke/seo-playbook-skills/trend-scan) | Analyze Google Search Console CSV exports for organic traffic trends, declining pages and queries, ranking losses, and traffic concentration. | Before [Phase 3 synthesis](https://seo-audit-site.vercel.app/methodology/phase-3-synthesis), once the exports are collected. |
| [claim-check](https://skills.sh/BigChrisCooke/seo-playbook-skills/claim-check) | Flag stale statistics, pricing, product limits, versions, feature claims, and missing verification dates for primary-source checking. | On the draft report before delivery, as part of [report QA](https://seo-audit-site.vercel.app/methodology/report-design). |

This collection supplies two core analysis skills and three helpers. Install the remaining upstream analysis skills separately. It does not include the optional `/seo-audit` orchestrator; their setup is explained on the [skill-pack page](https://seo-audit-site.vercel.app/skill-pack).

### Skill names and existing audit files

Use the published skills below. Older audits keep their existing evidence filenames; these filenames are storage locations, not skill commands.

| Invoke | Source | Save audit evidence as |
| --- | --- | --- |
| `/ai-seo-better-than-corey-haines` | [GitHub](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/ai-seo-better-than-corey-haines) · [skills.sh](https://skills.sh/BigChrisCooke/seo-playbook-skills/ai-seo-better-than-corey-haines) | `skills/ai-seo.md` |
| `/schema-markup-better-than-corey-haines` | [GitHub](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/schema-markup-better-than-corey-haines) · [skills.sh](https://skills.sh/BigChrisCooke/seo-playbook-skills/schema-markup-better-than-corey-haines) | `skills/schema-markup.md` |
| `/competitors` | [GitHub](https://github.com/coreyhaines31/marketingskills/tree/main/skills/competitors) | `skills/competitor-alternatives.md` |

Corey's comparison-page skill is now named `competitors`. Install it and the other two upstream dependencies separately:

```bash
npx skills add coreyhaines31/marketingskills --skill programmatic-seo site-architecture competitors
```

If using the standalone runbook without our optional orchestrator, also install `seo-audit` from that upstream repository. If using our orchestrator, it supplies that checklist itself; do not replace it with the upstream skill of the same name.

Before analysis, resolve each required skill by its published name. If one is missing, link its source above and provide the install command; mark it blocked until installed. Do not silently use an older local `ai-seo` or `schema-markup` copy. If an upstream skill cross-references those older names, route AI visibility and structured-data work through the published variants above. Use the runbook's audit-only scope and verification rules throughout.

### Verify this release and the complete installation

**Playbook release: `2026-11-06.1`.** The current [release manifest](https://seo-audit-site.vercel.app/handover/release.json) lists SHA-256 hashes and byte counts for the clean downloads. At session start, read this file from disk and report its absolute path and release. Compare with the live manifest; do not infer freshness from a download timestamp or file size. A working copy's hash will change when its Ledger is edited. Preserve that Ledger when upgrading instructions, and record the new release only after applying them.

For Claude Code, run these commands **from the audit project folder**. They install complete packages into that project. For Codex or Cursor, replace `claude-code` with `codex` or `cursor`.

```bash
npx --yes skills add BigChrisCooke/seo-playbook-skills --skill claim-check trend-scan remove-ai-slop-without-removing-ctas-and-good-marketing-copy ai-seo-better-than-corey-haines schema-markup-better-than-corey-haines --agent claude-code --copy --yes
npx --yes skills add coreyhaines31/marketingskills --skill programmatic-seo site-architecture competitors --agent claude-code --copy --yes
```

For the standalone runbook, also run `npx --yes skills add coreyhaines31/marketingskills --skill seo-audit --agent claude-code --copy --yes`. Skip that command if using our optional orchestrator, which supplies the checklist under the same name.

Download [check-skills.py](https://seo-audit-site.vercel.app/skill-pack/check-skills.py) into the audit project, then run:

```bash
python check-skills.py --project . --standalone
```

Omit `--standalone` when using our optional orchestrator. The checker performs no installs or network requests. It checks all five public packages against the published file hashes, verifies the three upstream entrypoints and their referenced resources, and runs the bundled Python helpers with `--help`. Missing scripts, changed package contents, or conflicting installed copies are reported with paths. `--skills-dir PATH` restricts checking to an explicitly selected skills directory; only use it after confirming that the agent will load that directory.

Save its JSON output as `audit-data/<client>/skill-preflight.json`. Record the release, selected skill paths, hashes, results, and fresh-session confirmation in the Ledger. A successful disk check does **not** prove that a running agent has refreshed its registered skill instructions. After installing or changing skills, checkpoint and start a fresh agent session, then confirm the selected paths before invoking them. Do not report an update as applied merely because a command ran.

The old editor name `edit-conversion-safe-blogs` maps to `remove-ai-slop-without-removing-ctas-and-good-marketing-copy`; use the published name. Use the two published analysis variants instead of old local `schema`, `schema-markup`, or `ai-seo` copies. `schema-detector` is not required: the published schema variant plus the two validators cover that step.

**Check delivery dependencies at the start:** a missing `claim-check` package or script blocks the delivery QA gate. Record it immediately, install the complete package, and verify it before marking delivery ready. Independent data collection may continue while it is blocked. Manual trend analysis must be labelled manual; it does not establish that `trend-scan` is installed. The conditional editor still requires its complete package when AI-written pages are in scope.

**SXO and drift setup:** a skill entrypoint alone is insufficient. If using `seo-sxo`, add `--with-sxo` to the checker; if capturing or comparing with `seo-drift`, add `--with-drift`. Use both flags when running both, and pass `--seo-bundle "<bundle>"` with the complete upstream repository root. The checker verifies the selected skill, the shared `fetch_page.py`, `parse_html.py`, and `render_page.py` files, and (for drift) `drift_baseline.py` and `drift_compare.py`. It checks managed runtime and Chromium readiness, then starts the scripts with `--help` in that runtime. It does not fetch pages or prove that a baseline was saved.

Obtain the complete shared script bundle from [the upstream repository](https://github.com/AgriciDaniel/claude-seo), following its current installation instructions, and record the source revision. Do not assume a skill-only CLI install includes repository-level scripts. Keep `requirements.txt` at the **repository root**, alongside `scripts/`; copying only `scripts/` breaks managed setup. Install the selected skill's complete folder (including references) for your agent and resolve its commands to this same bundle.

Replace `<bundle>` below with the real repository path. These Python entrypoint commands work in PowerShell and POSIX shells; the upstream Bash launcher `<bundle>/scripts/claude-seo setup` and `doctor --json` are alternatives when Bash is available:

```bash
python "<bundle>/scripts/runtime.py" setup
python "<bundle>/scripts/runtime.py" doctor --json
python check-skills.py --project . --standalone --with-sxo --with-drift --seo-bundle "<bundle>"
```

Omit `--standalone` when using our orchestrator, and omit the optional flag for any step not being run. Require **both** `ready: true` and `browser_ready: true`; a zero doctor exit code alone can still mean Chromium is missing. Use `python "<bundle>/scripts/runtime.py" run <script.py> ...` for subsequent commands so they use the managed environment, rather than the system Python. Then verify an actual rendered fetch on a target page (`run render_page.py <url> --mode always --json`): check its status, error, `mode_used`, and content. Preflight success does not substitute for this evidence.

If setup is incomplete, record the affected step as unavailable and continue independent audit work. A manual SERP/page-type review is a separately labelled fallback; for CSR/hybrid/unknown pages it needs rendered evidence, not just response HTML. Even a static page requires an explicit response-versus-rendered comparison before treating response HTML as sufficient. A hand-built JSON snapshot is manual evidence, **not** a completed `/seo-drift` baseline; retain the setup action for the next cycle.

For a manual install, copy each whole skill directory, including its scripts and reference files. These skills do not depend on a particular user's home folder. Browse the [skills.sh collection](https://skills.sh/BigChrisCooke/seo-playbook-skills) or [installation guide](https://github.com/BigChrisCooke/seo-playbook-skills#install).

**Other analysis skills:** Install `programmatic-seo`, `site-architecture`, and `competitors` using the upstream command above. The optional `seo-audit` orchestrator is available on the [skill-pack page](https://seo-audit-site.vercel.app/skill-pack).

**Two analysis helpers in the public playbook collection (built 4 September 2026).** Both run on plain Python with nothing to install, no logins and no API keys, so they work on any machine including a client's. They cover the two things nothing else did:
- `trend-scan` — works out whether traffic is going up or down, what dropped, and how much rides on one page, from the CSV files you export from Search Console. It runs first in §5.1, before you write anything. It always prints the flattering long-period total next to the recent trend, so the good number can never travel on its own.
- `claim-check` — finds the things you have written that might have gone out of date, says which ones have a date on them, and flags the ones nobody has checked in a while. Run it on any draft before it goes out, and on someone else's skill files before you trust them with a client's report.

**Published corrections:** The former local `ai-seo` and `schema-markup` patches are now distributed as `ai-seo-better-than-corey-haines` and `schema-markup-better-than-corey-haines`. Installing these variants includes the corrections and supporting references. Their descriptions and comparison notes explain the specific changes; the names do not imply a completed head-to-head performance benchmark.

The former local `schema-detector` is not a runbook dependency. The public schema variant and validator evidence now cover the schema review; readers do not need a private patch.

---

### Missing browser or PageSpeed quota: continue with explicit limits

Playwright is one browser option, not a global audit gate. Test whichever browser capability the agent actually has; if none can access authenticated tools, request GSC/GA4 CSV exports through F-FILE and continue public crawl, source, sitemap, and supplied-file analysis. Record browser-only/rendered checks as unavailable until evidence arrives. Do not infer a rendering pass from raw HTML. Tool unavailability is a limitation of this audit environment, not evidence that the client's website is broken.

For PageSpeed HTTP 429, record the response and URL/strategy, check for an already configured `PAGESPEED_API_KEY` or `GOOGLE_API_KEY` without displaying either value. Prefer the dedicated PageSpeed key; if absent or unusable, try the existing Google key once. Pass the selected value as the API key and verify the response: its environment-variable name does not guarantee that PageSpeed is enabled, permitted by key restrictions, or within quota. Redact keys from commands, URLs, logs, and saved evidence. Do not repeatedly call the same anonymous endpoint. A new key is optional and does not guarantee quota. Try a human-supplied PageSpeed report or local Lighthouse when Chrome and the runtime are available; neither requires Playwright. Keep Lighthouse lab measurements separate from field Core Web Vitals. If no route is available, record Performance as **not measured** and continue the audit. Ask once for the missing evidence; do not wait indefinitely or create cloud accounts during the audit.

A report may be delivered with these explicitly documented evidence gaps once the applicable analysis and claim-check QA are complete. Mark affected collection rows unavailable with their reason and collection action; do not mark them passed. With missing performance or other category evidence, show measured categories but **withhold the overall 0–100 Health Score** until its inputs exist. Do not substitute zero, invent a score, or silently redistribute weights. This evidence-gap rule takes precedence over instructions elsewhere to display a total score or wait for every collection row.

Sources: [PageSpeed API setup](https://developers.google.com/speed/docs/insights/v5/get-started) and [Lighthouse execution options](https://developer.chrome.com/docs/lighthouse/overview).

## Data Maturity — What You Can Run When

Not all sites have the same data available. A brand-new site has no GSC performance history. A site mid-migration has incomplete data. Running data-hungry skills against thin data produces generic recommendations. Use this table to decide what's appropriate before starting.

### Site stages

| Stage | GSC data available | GA4 data available | What to run |
|---|---|---|---|
| **New site / just launched** (0–4 weeks) | Coverage only (indexing status, 404s) | None or unreliable | Squirrel Scan + PageSpeed only. Fix code-level issues. Hold skills. |
| **Post-migration** (4–8 weeks) | Early performance data (low volume, noisy) | Partial | Squirrel Scan + PageSpeed. Run `/schema-markup-better-than-corey-haines`, `/site-architecture`, `/programmatic-seo` (strategy-level). Hold `/seo-audit`. |
| **Establishing** (2–4 months) | Meaningful performance data (queries, CTR, impressions by page) | Reliable channel + landing page data | Full Phase 1 data collection + all 6 skills. This is the minimum for a useful `/seo-audit` run. |
| **Mature site** (4+ months, no migration) | 12-month history available | Full funnel data | Full audit. Year-over-year comparisons possible. `/seo-audit` most specific here. |

### Which skills need which data

| Skill | Minimum data required | Can run without GSC? |
|---|---|---|
| **Squirrel Scan** | None — code-level crawl | ✅ Always run first |
| **PageSpeed Insights** | None | ✅ Always run |
| `/programmatic-seo` | Site structure + business context | ✅ Yes — strategy output is data-independent |
| `/site-architecture` | Existing page list + content structure | ✅ Yes |
| `/schema-markup-better-than-corey-haines` | Squirrel Scan output | ✅ Yes |
| `/competitors` | Competitor names (ask client — don't guess) | ✅ Yes, once competitors confirmed |
| `/ai-seo-better-than-corey-haines` | Top commercial queries helpful but not required | ⚠️ Generic without query data |
| `/seo-audit` | 4+ weeks GSC performance data (queries + pages CSV) | ❌ Output is generic without it |

| [Remove AI slop without removing CTAs and good marketing copy](https://seo-audit-site.vercel.app/methodology/phase-2-skills) | Identified AI-written page text, links, and conversion goal | ✅ Yes — review audit copies, even on a new site |
| [trend-scan](https://seo-audit-site.vercel.app/methodology/phase-3-synthesis) | GSC Dates CSV for direction; Pages/Queries CSVs for concentration; comparable prior/recent exports for movers | ❌ Record unavailable or insufficient history rather than inventing a trend |
| [claim-check](https://seo-audit-site.vercel.app/methodology/report-design#6-verify-time-sensitive-claims-before-delivery) | A draft report or other text containing factual claims; source access for verification | ✅ Yes — does not require traffic history |

The three [public playbook helpers](https://seo-audit-site.vercel.app/methodology/overview#install-the-playbook-skills) have different data needs from the core analysis skills. Holding traffic-dependent analysis on a new site does not prevent editorial review or claim checking. During an audit, record recommended fixes and work on evidence copies; implementation follows the separate action runbook.

### What's always actionable regardless of data age

Squirrel Scan findings are code-level — they don't depend on traffic history. Verify and prioritize these on any site at any stage:
- Schema validation errors (e.g. `Organization.logo` type mismatch)
- Missing H1 tags
- Orphan pages (internal linking gaps)
- Oversized images
- Missing or duplicate meta descriptions
- Missing alt text
- Verified crawl/security blockers. Do not promote generic missing-header warnings on static sites; check GSC Security Issues separately because it is the authoritative Search report.
- E-E-A-T gaps (no Contact page, no Privacy Policy)

These should be fixed before Google does more recrawling — not after you've collected more data.

### Migration-specific timing

| Milestone | Action |
|---|---|
| Pre-migration | Squirrel Scan + PSI + GSC export + GA4 export of **old** site. **`/seo drift baseline <url>` on every top organic landing page** — this is the diff target post-launch (see Phase 4: Drift Monitoring). |
| Launch day | Submit new sitemap in GSC. Run Squirrel Scan on new site immediately. **`/seo drift compare <url>` against each pre-migration baseline** — flags every silent regression (lost canonicals, dropped schema, H1 changes) before Google recrawls. |
| 2–3 weeks post-launch | GSC will show early indexing data (coverage, crawl errors). Fix 404s, redirect errors. Re-baseline post-fix URLs once stable. |
| 4–6 weeks post-launch | First meaningful GSC performance data appears. Run `/schema-markup-better-than-corey-haines`, `/site-architecture`, `/programmatic-seo`. |
| 3 months post-launch | Run full audit cycle with all 6 skills. This is when `/seo-audit` becomes genuinely specific. |
| Ongoing | Rerun Squirrel Scan quarterly to catch site-wide regressions. For retainer clients, run `/seo drift compare` monthly on baselined URLs to catch per-deployment regressions Squirrel Scan would only surface at the next quarterly run. |

---

## Overview

The audit runs in three phases:

1. **Data collection** — gather raw exports before running any skills
2. **Skill application** — run each skill against the collected data, one at a time
3. **Synthesis** — combine outputs, deduplicate, prioritize, structure

The key insight: **skills don't replace data collection, they interpret it.** Start with a compact Site Profile and route only the modules that apply, then collect the evidence. Running a skill against thin or irrelevant data produces generic recommendations.

---

## Phase 1: Data Collection Checklist

Collect all of this before invoking any skills. The more complete the data, the more specific the skill outputs.

### Site Profile and conditional router

Before opening tools, inspect the live site and available repository/deployment context. Record: approximate URL count; CMS/framework/hosting; static/SSR/CSR/hybrid rendering; repository/CMS/deploy access; markets/languages; ecommerce, local, publisher, image/video, and public internal-search features; log access; and available analytics/search tools.

Use that profile to activate only relevant modules. CSR/hybrid/unknown activates expanded response-vs-rendered testing; structured data activates Search Appearance outcome tracking; public internal search activates the bounded indexability/reflection test; existing content activates the refresh/merge/prune register; confirmed competitors plus validated queries activate the historical SERP panel; large/rapidly changing or demonstrably crawl-constrained sites activate deeper Crawl Stats/log analysis. Available source/CMS access plus an identifiable stack activates the CMS/framework implementation adapter. Mark a conditional module N/A with its reason rather than silently skipping it. Start a persistent dated `change-events.md` for migrations, deployments, template/plugin releases, content edits, analytics changes, and known incidents.

### CMS/framework implementation adapter — conditional

An adapter translates an evidence-backed recommendation into the client's actual implementation surface. It is not a generic platform checklist and does not activate merely because the framework name is known. Activate it when source or CMS access exists and at least one recommendation may be implemented; otherwise record `N/A — no implementation access/action`.

Save `implementation-adapter.md` with:

- detected CMS/framework, installed version/major, rendering mode, hosting adapter, build command, deployment path, and evidence for each;
- current primary documentation reviewed, source date, version fit, and any uncertainty;
- a map of `action/root cause → shared config/layout/component/template/content field → affected URL pattern → representative affected and unaffected tests`;
- local, built-output, deployed, and live verification commands/checks;
- rollback at the same shared level, plus recurring post-deploy and upgrade checks.

Do not prescribe a plugin, file path, API, or framework feature from memory. Inspect the project first, research the installed major against current primary documentation, and keep an action in Researching when the shared source is unknown. Do not bundle dependency/framework upgrades into an SEO fix unless the upgrade is separately justified and approved.

**Initial Astro adapter.** For an Astro project, inspect `package.json`/lockfile, `astro.config.*`, `src/pages/`, shared layouts/head components, content collections or other content source, sitemap integration, hosting config, and the actual build output. Map recommendations to the smallest shared source:

- Validate `site`, `base`, trailing-slash policy, output mode, hosting adapter, and integrations together; the configured deployment URL is used when Astro generates absolute URLs such as sitemap/canonical values.
- Treat `src/pages/` as the route inventory. For static output, confirm dynamic routes are deliberately produced by `getStaticPaths()` or the project's current version-equivalent content pipeline; for on-demand routes, verify server output and the matching deployment adapter.
- Centralize shared title, description, canonical, robots, Open Graph, Twitter, and JSON-LD behavior in the actual layout/head component, while keeping page-specific facts in typed props/frontmatter/content fields. Never “fix” a shared default by making every page identical.
- Validate `@astrojs/sitemap` against the intended canonical/indexable route set. Exclude non-indexable routes. Add per-URL `<lastmod>` only when a reliable substantive-change source exists; never stamp build/audit time onto unchanged pages.
- Run the repository's declared build, inspect representative generated HTML and sitemap output, then verify the deployed and live URLs. A successful build alone is not live SEO acceptance.

Primary Astro references: [configuration](https://docs.astro.build/en/reference/configuration-reference/), [routing](https://docs.astro.build/en/guides/routing/), [integrations](https://docs.astro.build/en/guides/integrations/), and [`@astrojs/sitemap`](https://docs.astro.build/en/guides/integrations-guide/sitemap/). Re-check them when the adapter runs.

### Google Search Console
- **Safety first** — record Manual Actions and Security Issues as clear, affected, or inaccessible. If affected, treat the authoritative Google evidence as a blocker before ordinary optimization. Do not browse a reported malware URL directly.
- **Freshness next** — record the preliminary Performance → 24 hours view with hourly clicks/impressions, compare with the previous 24 hours where available, and check Google's Search Status Dashboard plus Search Console data anomalies for overlapping incidents. Preliminary data is an alert signal, not finalized evidence or a reason by itself to change or roll back the site.
- **Performance export** — 12 months, all queries, all pages, all countries. Export both the queries table and the pages table as CSV.
- **Indexing exports** — three separate exports:
  - "Not indexed" → filter by "Crawled — currently not indexed" → export URL list
  - "Not indexed" → filter by "Discovered — currently not indexed" → export URL list
  - "Not indexed" → filter by "Duplicate, Google chose different canonical than user" → export URL list
  - "Pages with issues" → 404 / not found → export URL list
- **Core Web Vitals** — screenshot of the CWV field data report for mobile and desktop

### GA4
- **Property name check (do this first):** confirm the property name matches the site you expect to be tracking. A property named "Documentation" or "Staging" may have been set up for a different purpose and later repurposed — or may be tracking a different subdomain entirely. If the name doesn't match the main site, verify the data stream URL before trusting any channel data.
- **Landing pages report** — date range matching your GSC export, all landing pages, with as many conversion events as you have configured. Export as CSV. For B2B SaaS: look for "marketplace link click", "pricing click", "get it now click", "total install" — whatever the client has set up.
- **Channel data quality check:** if the Direct channel has more than 3× the sessions of Organic Search and an engagement rate below 25%, flag it before using it in analysis. For software that runs inside third-party tools (Jira plugins, Salesforce apps, browser extensions), the Direct channel typically absorbs users accessing help pages from within the host app — the referrer is stripped at the host platform level. These sessions look like Direct but are existing customers, not acquisition traffic. The Unassigned channel being large is a secondary symptom of the same issue.

### Keyword research — MANDATORY before any content recommendation

Do not recommend a single content piece, page, or cluster without keyword data behind it. The inselnova audit (2026-05) recommended an entire content plan — "best browser strategy games," "how to build a game with AI," genre guides — on the *assumption* that these had "real search volume, low competition." No volume or difficulty data was ever pulled. The client caught it immediately ("Did we do research on search volumes or just make this assumption up?"). It made the whole content section untrustworthy in one stroke.

Rules:
- Pull actual search volume and difficulty for every head term you propose targeting. Free sources: Google Keyword Planner, Search Console's own query data (what's *already* earning impressions is the strongest signal), Bing Webmaster, autocomplete + "People also ask" for intent, and a manual SERP scan for difficulty.
- If you genuinely can't get volume data, **say so and label the recommendation a hypothesis** ("untested — no volume data pulled"), don't assert "real search volume" or "low competition."
- Never write "100x larger audience," "high volume," "low/zero competition" unless you can point at the number. Those phrases are the tell that you're guessing.
- Separate *audience size* from *audience fit*. A bigger audience that won't convert (developers reading a build-in-public post who will never play the game) is worse than a small one that will. Size isn't the metric; qualified intent is. Ask "does this reader become a user?" before "how many are there?"
- Beware recommending keywords that sound on-brand but nobody searches. Example flagged by the client: "inselkampf wiki" / "inselkampf guide" — the game is dead, so people may type "inselkampf" but almost never "…wiki/guide." Check the actual query volume in GSC before building around a long-tail variant.

**Free keyword tools — the standing stack (use these, not guesses):**
- **Google Autocomplete** (`http://suggestqueries.google.com/complete/search?client=firefox&q=<term>`) — returns the queries Google actually suggests for a seed. A suggestion means real, recurring demand; an empty result (e.g. "inselkampf alternative" → nothing) means nobody searches it. Free, no account, scriptable in a loop over seed terms. The fastest demand/no-demand filter; run it first.
- **Google Trends** (trends.google.com) — relative interest over time, related + "breakout" queries, geography. Free, no account. Use for direction, seasonality, and rising terms — not absolute volume.
- **Google Keyword Planner** — the most authoritative *free* volume source: banded monthly volumes (e.g. 100–1K) + competition. Needs a Google Ads account but **no ad spend**. Set one up once per consultancy; reuse across clients.
- **Bing Webmaster Tools → Keyword Research** — actual volume estimates, free with site verification (you likely already have this for the client).
- **The live SERP itself** — the only honest difficulty signal without a paid tool. Read *who* ranks: Quora / Reddit / AlternativeTo / forum threads → a new low-authority site can compete; freetogame / mmobomb / high-DA editorial listicles → it can't, and the play becomes "get listed on them" (directory + backlink), not "outrank them" (content). Capture PAA, "People also search for," and "Related searches" for intent.
- **The client's own GSC query data** — the strongest first-party signal: queries already earning impressions are proven demand against this exact domain. Mine this before reaching for external tools.

**Method:** seed 5–10 terms → autocomplete-expand each → keep only variants whose intent the product can satisfy (drop "single player/offline" for a multiplayer game) → band by volume (Keyword Planner/Bing) → grade difficulty by reading the live SERP → output a short table: `query | demand signal | difficulty | product fit | verdict`. If a term has no autocomplete and no GSC impressions, it is not a target — say so and move on. Never carry a keyword into the content plan that failed this filter.

**One-time setup — do this before the next audit (highest-leverage thing missing from the kit).** Create a free **Google Keyword Planner** account: ads.google.com → sign in → when prompted to build a campaign, choose **"Switch to Expert Mode" → "Create an account without a campaign"** (you never create or fund an ad) → then **Tools → Planning → Keyword Planner → "Get search volume and forecasts."** Paste your candidate terms, set the country, export. It's free, gives banded monthly volumes (e.g. 100–1K) and competition, and the only friction is the one-time account creation — after that it serves every client. **Autocomplete and SERP reads tell you a query exists and how hard it is; only Keyword Planner (or Bing Webmaster) puts a number on it.** Until it's set up, every "volume" claim in a report is a guess — which this methodology now forbids. Note: Keyword Planner requires an interactive Google login, so it's a *human* setup step the consultant does once; an agent can't self-provision it.

### PageSpeed Insights
- Run on the homepage (mobile). Screenshot or note: Performance score, LCP, TBT, FCP, CLS.
- If time allows: run on the top 3-5 landing pages by organic traffic.
- The "Diagnostics" → "Third-party summary" is the most useful section — note each third party and its estimated CPU time.
- **Network dependency tree:** in the "Diagnostics" section, expand the network dependency tree and scan for CDN or font domains that don't match the production domain. A staging or test CDN domain serving fonts or assets in production (e.g., fonts loading from `staging.clientvendor.eu`) is a common source of LCP regression that's invisible without examining the full request chain. Each misrouted font request can add 2+ seconds to LCP.

### Squirrel Scan — MANDATORY, run this before any skills

**Do not skip.** Without Squirrel Scan data, skill outputs are generic and the specific URLs behind GSC's "crawled — currently not indexed" count remain unknown. The Togetha audit was weaker for not having this. The CLI is already installed on this machine — there is no excuse to skip it.

**Run the crawl:**
```
squirrel audit https://[client-domain] --max-pages <page-limit> --coverage full --format llm --output squirrel-report.txt
```
Flags: `-m/--max-pages` (page limit), `-C/--coverage` (use `full` for thorough audit), `-f/--format` (use `llm` for Claude-readable XML output), `-o/--output` (save to client data folder). Run `squirrel audit --help` to confirm current flag syntax. Replace `<page-limit>` with a numeric limit chosen from the sitemap URL count and expected crawl scope, leaving room for redirects and non-sitemap URLs. Discovered URLs can exceed sitemap counts; there is no universal safe multiplier. If the crawl reports that it capped, or reaches the configured limit without confirming completion, increase the limit and re-run. If scope or resources require stopping, label it a **partial crawl**. Record sitemap count, discovered/audited counts, limit, exclusions, and completion status alongside the output. Do not present a capped score as a full-site score or compare scores from different crawl scopes without explaining the difference. Save the output file to the client's data folder alongside the GSC exports.

**What it gives you that nothing else does:**
- The actual URLs of every page Google crawled but rejected — not just the count GSC shows, but the specific pages
- Every broken external link by URL
- Every internal nofollow link (page builders misconfigure these constantly)
- JSON-LD validation errors per URL with the specific field that's wrong
- Missing or misconfigured security headers
- Credential or API key leaks in HTML source
- Accessibility errors at scale with the specific elements failing
- Scores across 18 categories that ground every recommendation in a rule ID

**Most valuable categories:** Structured Data (almost always fails — reveals schema bugs), Security (headers + credential leaks), Links (internal nofollow, broken external), Accessibility (scale + specific elements).

**After the crawl:** paste the full XML output or at minimum the category scores + top failures into Claude alongside each skill prompt. This is what makes skill outputs cite specific URLs and rule IDs rather than generic advice.

### Manual page audits
- Homepage: View Source + PSI
- Top commercial/product page
- Top organic landing page by traffic
- Pricing page
- One blog post

On one representative URL, compare the HTTP response/page source with the rendered DOM for status/final URL, title, meta description, canonical, robots, H1, primary content, crawlable links, and JSON-LD. If the site is CSR/hybrid/unknown or a material difference appears, expand to up to three representative templates and corroborate one material difference with URL Inspection's Google view or the Rich Results Test. Static/SSR sites may mark the expanded module N/A only after a representative comparison shows no material dependency. Store the matrix in `js-render-parity.md`.

### Structured data outcome loop

Validate representative page types in both Google's Rich Results Test and Schema.org Validator, but do not stop at validity. Before recommending a change, capture the applicable GSC Enhancement report and Performance → Search appearance baseline: appearance type, valid/invalid where reported, impressions, clicks, CTR, date range, and example URLs. After an approved schema change, revalidate live immediately and compare the same appearance type at 2/4/8 weeks. Keep three states separate: **valid**, **eligible**, and **shown**. Valid markup never guarantees display.

### Evidence-based content refresh / merge / prune

Maintain a canonical URL register with comparable finalized GSC periods, GA4 conversions, links/referrals, user and business value, substantive update date, overlap/successor, current SERP/query evidence, and technical state. Age, word count, low traffic, or a `>30%` loss only trigger review.

Diagnose demand decline, seasonality, competitiveness/content loss, SERP/CTR change, technical/indexing, tracking anomaly, volatility, or unknown before deciding. Then choose Protect/Refresh/Merge/Differentiate/Redirect/Noindex/Remove/Investigate. A refresh requires a fixable gap; merging requires substantially overlapping user tasks; a permanent redirect requires a meaningful replacement; no replacement means `404/410`. Destructive decisions are Red and need explicit human approval after checking conversions, inbound/internal links, navigation/support/legal value, recovery limits, and the full redirect/canonical/sitemap plan.

### Crawl Stats and server logs — conditional

Record the GSC Crawl Stats headline baseline when available: 90-day range, requests, download size, average response time, host status, response codes, file types, crawl purpose, crawler types, and material spikes/drops. Below roughly 1,000 URLs with healthy crawling and no direct constraint, log analysis is normally N/A. Google's current advanced crawl-budget guidance is narrower still, focusing on very large/rapidly changing sites or a material discovered-not-indexed backlog.

Request bounded server logs only when evidence warrants them: size/change rate, parameter/facet space, migration, host/5xx/429 trouble, important-page recrawl lag, or a material discovered backlog. Define date range, fields, privacy/retention, and hypotheses first. Verify Google crawler requests through reverse/forward DNS or published IP ranges because user-agent strings can be spoofed. Crawl-volume change alone is not a budget diagnosis.

Primary references: [Crawl Stats](https://support.google.com/webmasters/answer/9679690), [crawl-budget guidance](https://developers.google.com/crawling/docs/crawl-budget), and [crawler verification](https://developers.google.com/crawling/docs/crawlers-fetchers/verify-google-requests).

### Backlink baseline and disavow safety

Export GSC's sampled top linked pages, linking sites, linking text, and internal links with property/date/coverage limits. Add Bing when available, and Ahrefs **only when it has been explicitly authorised for this client** (it is connected machine-wide but billed to one client's account — see the runbook's §0 standing rules and F-AHREFS), but keep each provider's index and counts separate. Use the baseline to protect valuable links, reclaim useful broken/redirected targets, and identify verified mention/outreach opportunities. Verify material source and target pages live.

Never let a toxicity score or suspicious-looking sample automatically produce a disavow recommendation. Google says most sites do not need the tool and misuse can harm performance. Disavow is Red and only enters consideration for a considerable artificial/paid/low-quality pattern plus a related Manual Action or credible link-scheme risk, after expert review, verification, and removal attempts. See [GSC Links](https://support.google.com/webmasters/answer/9049606) and [Disavow guidance](https://support.google.com/webmasters/answer/2648487).

### Internal site search — conditional indexability and reflected-input check

If the site has a public internal search, test one normal query and one harmless URL-encoded HTML-like marker such as `<b>audit-search-check</b>`. Capture the result page's status, canonical, meta robots / `X-Robots-Tag`, sitemap and internal-link exposure, title/H1/body reflection, page source, and rendered DOM. The purpose is to answer two questions: can generated search-result URLs be indexed, and is user-controlled text rendered as text or interpreted as markup?

Calibrate the outcome:

- No internal search: N/A.
- Crawlable `noindex` plus escaped text: pass or low observation.
- Indexable results plus escaped text: Medium; recommend `noindex`, sitemap removal, and controlled crawl paths.
- Markup interpreted as HTML: High and developer/security review. Call it unsafe reflected-input handling, not confirmed XSS; the audit does not attempt execution.

Do not use an exploit payload. If `noindex` is recommended, keep the URL crawlable so Google can see the directive—blocking it in `robots.txt` is not a substitute. Implementation must use context-appropriate output encoding and safe framework/DOM sinks. Re-check current [Google `noindex` guidance](https://developers.google.com/search/docs/crawling-indexing/block-indexing) and the [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) before acting. The audit trigger is documented in [Mark Williams-Cook's internal-search case](https://markwilliamscook.com/problems-with-indexable-internal-search-pages/).

### SERP captures (with page-type classification — SXO input)

- Freeze a historical panel of 5–10 validated commercial query clusters with locale, device, collection method, client landing URL, confirmed competitors, and the fixed page-type taxonomy. Preserve this configuration across cycles; changes need a dated reason.
- Run the panel in incognito or the declared repeatable collection route. Capture personalized/local volatility and incomplete-result limitations.
- Screenshot the full SERP including AI Overview, PAA boxes, featured snippet, and organic results.
- Note: which competitors appear where? Is there an AI Overview? Is the client cited?
- **Classify every top-10 result by page type.** Use a fixed vocabulary so patterns are comparable across keywords: `product`, `comparison`, `alternatives-list`, `blog-post`, `glossary`, `tool/calculator`, `landing-page`, `docs`, `forum-thread`, `video`, `aggregator`. Record as a one-line table per keyword: `keyword | dominant type (count) | client URL (if present) | client's page type`.
- **Identify the dominant page-type pattern.** If 7+/10 results share a type, that's what Google has decided the query rewards. If the top 3 share one type and positions 4-10 are mixed, that's a strong signal too.
- **Flag page-type mismatches.** If the client ranks (or wants to rank) for the query with a page that isn't the dominant type — e.g., a blog post against a SERP of 8 product pages — that's an SXO finding. It typically outranks technical findings in importance: a 95/100 technical page in the wrong format will not beat a 70/100 page in the right format.
- **Note the SXO-to-AI-Overview interaction.** When the dominant SERP type is `glossary` or `blog-post` and an AI Overview is present, the AI Overview is usually pulling from those pages. A client targeting that query with a product page is invisible to both organic and AI.
- **On later cycles, write the delta.** Record entrants/exits, page-type consensus, feature-owner changes, client landing-URL switches, and confirmed competitor movement. Inspect live pages before attributing a cause; rank, `<lastmod>`, or hash change alone does not prove a strategy.

**Why this matters:** the methodology's existing SERP capture step recorded *who* ranked but not *what shape of page* ranked. Page-type mismatch is the most common cause of "we rank for everything except our actual category" — and it's exactly the kind of reframing finding the Executive Summary section is designed around. Don't outsource this to an agent; the page-type judgment calls (e.g., "is this comparison page or alternatives-list?") are where consultant value lives.

**Tooling — `/seo-sxo` (from claude-seo):** the `seo-sxo` skill is installed at user level (cherry-picked from [AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo)). Invoke it per URL:
- `/seo sxo <client-url>` — auto-detects keyword from title+H1 overlap, then runs SERP analysis, persona scoring, and page-type mismatch detection
- `/seo sxo <client-url> <keyword>` — pins the analysis to a specific commercial query
- `/seo sxo wireframe <client-url>` — generates IST/SOLL (current vs target) wireframe

Use it as a structured second pass after you've done the manual page-type classification above — not as a replacement. The skill's persona scoring (B2B buyer, technical evaluator, etc.) is useful raw input; the decision about which findings actually go in the report stays with you. References live at [~/.claude/skills/seo-sxo/references/](file:///C:/Users/Mr.%20Big%20Boss%20Chris/.claude/skills/seo-sxo/references/) — `page-type-taxonomy.md` is the source-of-truth vocabulary if you're unsure how to classify a result.

**Data prerequisite — pull this from the client before running `/seo sxo`:**
1. **The exact landing URL** that ranks for the target query (not the query-average position the audit body usually records). Get it from GSC → Performance → Search results → filter Query = "<target>" → Pages tab → export. The query-average position can be misleading: it averages across multiple URLs (the Apwide audit recorded "position 17" on the head term, but the GSC Pages export later showed the actual ranking URL was a blog post at avg pos 9.5-15, completely changing the strategic question from "which URL should rank" to "how to deepen the URL that already does"). If desktop and mobile rank different URLs, capture both.
2. **2-3 additional URL/keyword pairs** for the same SXO pass — homepage + head term, top conversion landing page + its primary query, top organic landing page + its primary query. Bundling avoids one-keyword tunnel vision.
3. **Confirmation that pip deps are installed** (see Dependency note below). Discovery works without them; execution doesn't.

**Dependency note:** use the complete shared script bundle and managed setup described above. Run the checker with `--with-sxo --seo-bundle "<bundle>"`, then verify a rendered target-page fetch through that same runtime. A skill-only install or a few successful package imports does not establish SXO readiness.

**Known WebSearch limitation:** the skill's SERP step expects top 10 organic; WebSearch typically returns 6-8. The dominant-page-type % is still directional with 8 results, but consensus confidence should be reported as "strong direction" rather than precise %. Also, WebSearch does not return PAA, featured snippet shape, or related searches — derive user-story inputs from the GSC query co-occurrence cluster instead (group all variants of the head term in GSC Queries.csv and read intent from the co-occurring queries). Note both limitations in the audit's SXO section.

### robots.txt + sitemap
- `https://[domain]/robots.txt` — paste contents into a text file
- `https://[domain]/sitemap_index.xml` — note structure and any missing sitemap types

---

## Phase 2: Skills — Run All Applicable Skills Before Synthesis

**The six core skills below are mandatory. A seventh, `/remove-ai-slop-without-removing-ctas-and-good-marketing-copy`, is mandatory when the kickoff answer confirms AI was used to write pages and is skipped only when the answer is no. Do not begin Phase 3 synthesis until every applicable skill has been run and its output saved. Squirrelscan tells you what's broken. These skills tell you what to build and how to grow. Skipping them produces a technical audit without a growth strategy.**

Use the checklist at the bottom of this phase to confirm completion before moving to Phase 3.

---

### What Each Skill Does

### `/seo-audit` (coreyhaines31/marketingskills)

**Minimum data required:** 4+ weeks of GSC performance data (queries CSV + pages CSV). Without it, output is generic SaaS SEO advice rather than findings specific to this site. Run this skill last among the six — both because it catches gaps in the other skills' outputs, and because it needs the most data to be useful.

**What it adds:** A systematic checklist of SaaS-specific SEO gaps applied against your collected data. The most important outputs for B2B SaaS:
- **SaaS content type gaps** — surfaces missing page types that are almost always absent: comparison/alternative pages, glossary/definitional content, feature depth pages. These are structural content gaps, not just technical issues.
- **INP (Core Web Vital)** — flags that INP replaced FID in March 2024 and is now a ranking factor. Sites with many blocking scripts commonly fail this and don't know it. The skill connects the blocking-script count from Squirrel Scan to INP risk.
- **Crawl budget fragmentation** — connects the subdomain count, parameter URLs, and thin-content issues to crawl budget. Useful framing for clients who don't understand why fixing these matters.
- **Content quality and policy risk** — test originality, accuracy, first-party experience/value, factual support, and policy compliance. Do not infer quality from an “AI detector” or isolated phrases; assess whether the page helps its intended user and adds something worth publishing.

**What to prompt:** "Apply the seo-audit skill against the following data: [paste GSC summary, PSI scores, Squirrel Scan category scores, notes from manual page audits]. The site is a B2B SaaS selling [product] on [platform]. Identify gaps specific to this data, not generic recommendations."

**Gotcha:** Run this skill twice — once with coreyhaines31 (more tactical, SaaS-focused) and once with the Anthropic version if available (more process-oriented). They surface different things. The Anthropic version added PAA as a distinct keyword target and per-competitor SERP feature tracking to the Apwide audit — neither appeared in the coreyhaines31 run.

---

### Remove AI slop without removing CTAs and good marketing copy

**Public skill:** [GitHub source](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/remove-ai-slop-without-removing-ctas-and-good-marketing-copy) ? [skills.sh listing](https://skills.sh/BigChrisCooke/seo-playbook-skills/remove-ai-slop-without-removing-ctas-and-good-marketing-copy). Invoke `remove-ai-slop-without-removing-ctas-and-good-marketing-copy` by name.

**Trigger:** The kickoff answer to *“Have you used AI to write any of your pages?”* is yes. Use the installed `remove-ai-slop-without-removing-ctas-and-good-marketing-copy` skill from [the public collection](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/remove-ai-slop-without-removing-ctas-and-good-marketing-copy). A no answer produces a reasoned skip; an unknown answer remains a human blocker rather than permission to infer authorship with an AI detector.

**Minimum data required:** Identified AI-written URLs or source files, full page copy, and every visible CTA, link, offer, positioning statement, proof point, and capability claim. If the human cannot identify the complete set, record that limitation and sample at least the highest-traffic page, highest-converting page, and one page from each materially different content template.

**What it adds:** A conversion-safe editorial review that finds generic or synthetic prose patterns without weakening the page's commercial job. It produces protected conversion contracts, working edits, integrity verification, and a summary of recurring and page-specific findings.

**How it works:** Identify the page's conversion goal, mark protected sections, snapshot the draft with the included Python conversion guard, edit the prose, then verify the protected content and links. The included prose rubric and final evaluation work without any separate local editing skill. Automated checks support the agent's editorial review; they do not establish factual accuracy or permission to publish.

**Audit boundary:** Run the skill only on copies stored under `audit-data/<client>/skills/remove-ai-slop-without-removing-ctas-and-good-marketing-copy/`; never change the live site, CMS, or repository source during the audit. Save the concise synthesis input to `skills/remove-ai-slop-without-removing-ctas-and-good-marketing-copy.md`. Working edits are evidence and proposed copy, not authorization to publish.

**What to prompt:** "Apply the complete remove-ai-slop-without-removing-ctas-and-good-marketing-copy workflow to these AI-written pages: [URLs/files]. Work only on audit copies. Preserve and verify every CTA, link, offer, positioning statement, proof point, and capability claim. Save per-page evidence and summarize recurring editorial risks with affected URLs for the SEO audit."

---

### `/programmatic-seo` (coreyhaines31/marketingskills)

**Minimum data required:** Site structure + business context only. This is a strategy skill — it doesn't need traffic data. Can be run on a brand-new site on day one. The output (cluster types, launch order, URL structures) is valid regardless of how much GSC data exists.

**What it adds:** A 12-playbook framework for identifying which types of pages to build at scale. For B2B SaaS, the five that consistently apply:

1. **Integrations** — "[product] [tool they use] integration" pages. Almost always the highest ROI pSEO cluster because intent is highest (they've already committed to a tool stack). Only works if real integrations exist — don't build these for imaginary integrations.
2. **Comparisons** — "vs competitor" and "alternatives" pages. Bottom-funnel, high intent.
3. **Personas** — "[product] for [industry/role]" pages. Useful when the client has clear customer segments and logo proof.
4. **Glossary** — "what is [term]" definitional pages. Highly scalable, feeds AI Overview defense, establishes category authority.
5. **Templates** — "[type] template" pages. High shareability, natural lead magnet for gated downloads.

**What to prompt:** "Apply the programmatic-seo skill against this site. The client sells [product], has confirmed integrations with [tools], and the top competitors are [X, Y, Z]. Primary customer segments are [segments]. What pSEO clusters are viable and in what order should they be built?"

**Key output to capture:** The recommended launch order (not just the full list), and the target URL structure for each cluster. Both go directly into the report.

**Gotcha:** The skill will generate 12 playbooks. Most won't apply. Filter hard — only include playbooks where the client has the underlying product reality (real integrations, real customer segments, real competitor landscape). Generic pSEO playbooks that don't connect to real product data produce content that doesn't rank.

---

### `/ai-seo-better-than-corey-haines` (BigChrisCooke/seo-playbook-skills)

**Minimum data required:** Business context + a confirmed persona + top commercial queries. Use query data where available; prompts generated from the product alone are hypotheses, not evidence of demand. The AI Overview suppression analysis needs GSC impressions/CTR data to be specific — without it, the output is framework-level rather than site-specific.

**What it adds:** An AI/GEO/AEO (Generative Engine Optimization / Answer Engine Optimization) framework. The most useful outputs:

- **Fixed prompt/citation benchmark** — a stable, bounded set of persona-context prompts that records observable web-search behaviour, brand mentions, client citations, and recurring cited domains by platform/date/locale.
- **Conversation and fan-out opportunity mapping** — uses validated keyword seeds, persona context, useful follow-ups, and any search queries the platform actually exposes; generated prompts remain hypotheses until independently validated.
- **Third-party presence strategy** — identifies the review sites, publications, directories, forums, and communities that the sampled answers actually cite, then separates on-site content work from accurate off-site inclusion/outreach.
- **No special-file shortcut** — Google says its AI search features have no additional technical requirements beyond ordinary Search eligibility. Do not award points or promise visibility merely for `/llms.txt`, AI-specific files, or special schema. If a client already maintains `llms.txt`, it may be checked as an experimental non-Google aid, but it is not a ranking or inclusion requirement.
- **Directional AI visibility** — within the fixed benchmark only, report the observed sample count and percentage mentioning/citing the client versus named competitors. Never present it as universal "share of AI voice"; prompts, platforms, models, location, and time all affect the result.
- **Standard structured data only where justified** — use supported schema that accurately matches visible content and passes the relevant validators. `ItemList` may describe a genuine visible list, but it is not an AI-inclusion switch.

**What to prompt:** "Apply the ai-seo-better-than-corey-haines skill to identify how [client] can improve visibility in AI-generated search results. Their top commercial queries are [queries]. Their confirmed competitors are [X, Y, Z]. They currently have [describe existing schema/tracking setup]."

**Gotchas:** The Wikipedia recommendation this skill generates is usually too aggressive for corporate clients. The safe framing: "ensure content worth citing exists, then pursue third-party citation" rather than "create a Wikipedia article." Wikipedia COI deletion risk is real. Also reject a page-per-prompt content plan: generated prompts are research inputs, and Google explicitly warns against scaled pages created primarily for query/fan-out variations.

**Research basis:** [Mark Williams-Cook's AI-platform keyword-research process](https://athenseo.com/knowledge-hub/keyword-research-for-ai-platforms/) and [Google's current guidance for generative AI features](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide). Re-check the primary platform documentation before every benchmark cycle.

---

### `/schema-markup-better-than-corey-haines` (BigChrisCooke/seo-playbook-skills)

**Minimum data required:** Squirrel Scan output (to validate current schema) + page type list. No traffic data needed — schema correctness is a code-level question. Can and should be run on new sites immediately after launch.

**What it adds:** Validates that the schema types you're recommending are correctly formatted and identifies the right schema for each page type. The most useful outputs:

- **Entity relationships** — connect entities consistently with `@id`; `@graph` can group them, but is not a Google requirement.
- **Per-page schema mapping** — choose types supported by the page's visible content and the feature's current requirements. A schema.org type does not automatically confer Google rich-result eligibility.
- **Validation evidence** — cite actual errors per URL and distinguish required from recommended properties. Check [Google's Organization guidance](https://developers.google.com/search/docs/appearance/structured-data/organization) rather than assuming every nested logo is invalid.

**What to prompt:** "Apply the schema-markup-better-than-corey-haines skill to identify the correct schema types for the following pages: [list page types]. Flag any common validation errors to watch for in WordPress/Yoast setups."

**Gotcha:** Feed this skill the collected validator evidence and AI-search analysis. Recheck any later schema recommendations against its findings before synthesis.

**Retired Google rich results:** The published `schema-markup-better-than-corey-haines` skill includes a dated eligibility table and primary-source references. Install that variant using the command above; no private local patch is needed. `HowTo` and `FAQPage` remain schema.org vocabulary, but their retired Google rich results must not be presented as opportunities. Schema.org validity, Google eligibility, and observed display are separate checks. Recheck [Google's documentation updates](https://developers.google.com/search/updates) before making current eligibility claims.

**Cross-check against a dated source.** Before recommending any type for a rich result, check it against `seo-schema` in [AgriciDaniel/claude-seo](https://github.com/AgricIDaniel/claude-seo), which maintains a dated deprecation table (HowTo Sept 2023, ClaimReview / VehicleListing / EstimatedSalary June 2025, SpecialAnnouncement 31 Jul 2025, Practice Problem 6 Jan 2026, FAQ 7 May 2026). It cites no source URLs, so treat it as a checklist to verify against Search Central, not as the authority itself.

---

### `/site-architecture` (coreyhaines31/marketingskills)

**Minimum data required:** Existing page list + planned content clusters (from `/programmatic-seo`). No traffic data needed. Run this after `/programmatic-seo` so you know what clusters you're building the architecture for — it's a refinement skill, not a discovery skill.

**What it adds:** IA (information architecture) and internal linking framework. The most reusable outputs:

- **Spoke-to-hub back-linking** — the most commonly missed internal linking rule: every spoke page must link back to its hub pillar, not just the hub linking to spokes. The specific wording to include in every spoke: "For the full guide to [topic], see [Pillar Page title]."
- **Footer column structure** — a four-column footer template (Product, Resources, Company, Legal) that acts as a free internal link on every page. Surfaces whether the current footer links to new pSEO pages that will be built.
- **Pillar/cluster architecture spec** — the formal structure for a content cluster: one pillar page targeting the head term, 5-8 spoke pages targeting long-tail variants, all linking bidirectionally.

**What to prompt:** "Apply the site-architecture skill to this site. The client's main content cluster should be around [head term]. They have existing blog posts at [URLs]. What does the pillar-spoke architecture look like and what's the internal linking plan?"

**Gotcha:** This skill is most useful when you already know what the content cluster will be (from the seo-audit and programmatic-seo skills). It's an architectural refinement, not a discovery skill. Run it after you've identified the clusters.

---

### `/competitors` (coreyhaines31/marketingskills)

**Minimum data required:** Confirmed competitor names from the client — nothing else. No traffic data needed. The blocker is always human, not data: do not guess competitors, and do not run this skill until the client has confirmed the names. A comparison page built on a wrong competitor assumption is worse than no page.

Ask what the competitors are! Don't assume, and check whether your guess is right...

**What it adds:** A framework for building comparison and alternative pages. The most distinctive output:

- **Format 4 (competitor A vs competitor B)** — the skill surfaces a fourth comparison page format that's frequently missed: *competitor A vs competitor B*, where the client enters as "the third option." For a market where two incumbents are well-known, a searcher comparing those two incumbents is already bottom-funnel. Appearing on that SERP with a "you haven't considered us" angle captures high-intent buyers who don't know the client exists. Neither incumbent can easily retaliate by building the same page.
- **Centralized competitor data file** — recommends maintaining a single YAML/JSON file with competitor pricing, features, and review data as the source of truth for all comparison pages. Prevents drift when competitor pricing changes.
- **Review mining methodology** — G2, Capterra, TrustRadius reviews are the best source for "common complaints" about each competitor. Mine these before writing comparison page copy — the copy writes itself.

**What to prompt:** "Apply the competitors skill. The client's product is [product]. Primary competitors are [X, Y, Z]. What comparison page formats should be built and in what order?"

**Gotcha:** The skill generates 4-5 page formats. For most clients, only 2-3 are realistic to build in a quarter. Prioritize the "vs main competitor" page first (most commercially obvious), then the "competitor A vs competitor B" Format 4 page (highest asymmetric value).

---

### Phase 2 Completion Checklist

Do not proceed to Phase 3 until all boxes are checked:

- [ ] `/seo-audit` — run and output saved
- [ ] `/programmatic-seo` — run and output saved
- [ ] `/ai-seo-better-than-corey-haines` — run and output saved
- [ ] `/schema-markup-better-than-corey-haines` — run and output saved
- [ ] `/site-architecture` — run and output saved
- [ ] `/competitors` — run and output saved (requires competitor names — ask client before running)
- [ ] `/remove-ai-slop-without-removing-ctas-and-good-marketing-copy` — run and output saved when kickoff says AI was used; otherwise explicitly skipped with the kickoff answer recorded

**Order note:** Run `/seo-audit` last. It catches gaps in all the other skill outputs, including the conditional AI-written-page review. Run `/competitors` only after confirming competitor names with the client (Phase 1 Ledger item 8) — do not guess.

---

## Phase 3: Synthesis Process

Running all skills generates a large volume of recommendations. The synthesis step is where the audit becomes useful.

### Before synthesis: run `trend-scan`

Use [trend-scan](https://skills.sh/BigChrisCooke/seo-playbook-skills/trend-scan) on the Google Search Console CSV exports collected in Phase 1. A Dates export establishes traffic direction; Pages or Queries exports show concentration, and comparable prior/recent exports identify declining or missing pages and queries. See the [GitHub skill instructions](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/trend-scan) for the helper commands and supported inputs.

Save the output as `skills/trend-scan.md` in the client audit folder. Use the recent trend alongside the longer-period total when deciding what leads the report. Investigate each flagged mover against the change timeline, technical evidence, and live search results; a detected decline does not establish its cause.

If history is missing, incomplete, or not comparable, record the limitation explicitly. Do not infer a healthy trend from a large aggregate total. [Install the public helpers](https://seo-audit-site.vercel.app/methodology/overview#install-the-playbook-skills) if the skill is unavailable.

### Step 1: Collect all skill outputs into one document
Paste each skill's output into a staging document with a clear heading for each skill. Don't edit yet — just collect.

### Step 2: Deduplicate
Multiple skills will surface the same finding (e.g., comparison pages appear in `/seo-audit`, `/programmatic-seo`, and `/competitors`). Keep the most detailed version; strip the others.

### Step 3: Reconcile the change timeline and calibrate causality

Before diagnosing a traffic or ranking mover, align the monthly series with `change-events.md`: deployments, migrations, template/plugin releases, content and analytics changes, GSC Manual Actions/Security Issues, Google Search Status incidents, and documented data anomalies. Keep preliminary 24-hour data distinct from finalized history.

A matching date is correlation. Use **"consistent with"** unless a rollback/reproduction, logs, or another controlled check confirms the mechanism. Do not prescribe automatic rollback solely because rankings fall within seven days; roll back for failed technical acceptance criteria or pre-agreed business guardrails, otherwise retain the change record and measure at 2/4/8 weeks with an unaffected comparison where possible.

### Step 4: Group by shared root cause

Map finding IDs to the common template, component, plugin, CMS field, or configuration before writing recommendations. Record the URL pattern, affected count, representative failing URL, proposed single fix, unaffected regression sample, and confidence. One shared mechanism becomes one recommendation and action even when it affects hundreds of pages. Use page-level actions only for genuinely isolated faults.

### Step 5: Reconcile content lifecycle decisions

Join the URL register with comparable search periods, conversion, backlink, user/business value, query→Pages, historical SERP, and technical evidence. Every affected URL gets one provisional decision: Protect, Refresh, Merge, Differentiate, Redirect, Noindex, Remove, or Investigate. Destructive routes remain Red/Human decision and cannot be based on age or traffic alone.

### Step 6: Compile evidence-backed content briefs

Every proposed new, refresh, or merge recommendation gets a brief before it enters the 90-day plan. State: action and URLs; confirmed persona/task/funnel/conversion goal; target query cluster with source/date/market; current URL(s) Google shows; live SERP intent/page type; unique first-party expertise, experience, data, examples, media, or proof; outline/questions; CTA; internal links; supported schema; facts/approvals still needed; acceptance criteria; baseline; and 2/4/8-week measurement.

AI may research and draft after approval, but it must not invent product claims, customer evidence, experience, statistics, or competitor facts. Do not produce one page per keyword/prompt variation or commodity summaries of existing results.

### Step 7: Cross-reference with raw data
Every recommendation needs to be grounded in the client's actual data:
- "Build comparison pages" is generic. "Build `/compare/golive-vs-enov8/` because Enov8 holds position 1-2 on the head term and Apwide is at position 17" is specific and defensible.
- Check each skill recommendation against the GSC, GA4, PSI, and Squirrel Scan data you collected. Drop recommendations that don't connect to a specific data point.

### Step 8: Assign tiers
Four tiers work well:
- **Tier 1 (Week 1):** Critical indexing bugs, any 404 bugs fixable in under 1h, broken schema on key pages, sitemap/robots breakage. (Security findings do NOT belong in Tier 1 — see the Security & Platform Risk section.)
- **Tier 2 (Month 1):** Highest ROI items — Marketplace/conversion optimization, performance, highest-impression content upgrades, tracking gaps
- **Tier 3 (This quarter):** Content cluster, comparison pages, pSEO launch
- **Phase 2 (Defer):** Items needing external data not yet collected (for example, a paid backlink index or server logs that §3's conditional crawl router genuinely requires)

### Step 9: Assign impact + effort
For each item:
- **Impact 1-5:** How directly does this item affect organic traffic, rankings, or conversions?
- **Effort:** T-shirt size (15min / 30min / 1h / half-day / 1 week / quarter+)

**No owner field.** The tool doesn't know the client's team or resources, so don't invent one — an invented "Dev/IT" or "Marketing" label reads as presumptuous and is usually wrong. Effort size already tells the reader whether it's a self-serve fix or a developer task; let them assign their own people.

### Step 10: Write the 90-day execution plan first
Before detailing individual recommendations, write the 90-day plan section. This forces you to decide what actually matters vs. what's just interesting to include. If an item doesn't make it into the 90-day plan, ask why it's in the report at all.

### Step 11: Answer the Acquisition Channel Questions — last, on purpose
The report closes with a Q&A section framed by one goal: **turn the website into a predictable acquisition channel.** The standing questions (runbook §5.7) cover website structure, conversion optimization, product pages, landing pages, lead magnets, SEO opportunities, and content strategy — plus the two focus questions: *what content attracts buyers vs. just traffic*, and *how blog → lead magnet → demo/trial should connect*. The section ends with three deliverables: a website improvement roadmap, a lead magnet plan, and content priorities for the next 6 months.

**Why last:** none of these is answerable from a single source. "Buyers vs. traffic" needs GSC *and* GA4 conversion paths; the lead-magnet plan needs the persona, the conversion architecture, *and* the SERP/demand data; the 6-month priorities need the tiers and 90-day plan to already exist so they can point into them instead of duplicating them. Answering early or piecemeal produces the generic strategy boilerplate the rest of this methodology exists to avoid. The AI answers every question itself, citing collected data — it never hands them to the client; where data is missing (no conversion tracking, say), the honest answer *is* the gap plus its Tier 1 setup action.

---

### Before delivery: run `claim-check`

Run [claim-check](https://skills.sh/BigChrisCooke/seo-playbook-skills/claim-check) on `<client-slug>-seo-audit-YYYY-MM-DD.md`. Resolve each flagged time-sensitive claim against a primary source: confirm it and record the source and verification date, correct it, or remove it. Save the verification notes as `skills/claim-check.md` in the client audit folder.

The script finds potentially stale or undated statements; the agent performs the source verification. A clean scan does not prove that the report is accurate. Complete the [report QA checks](https://seo-audit-site.vercel.app/methodology/report-design#6-verify-time-sensitive-claims-before-delivery) before generating the action runbook.

---

## Phase 4 (Retainer / Migration): Drift Monitoring

The audit produces a point-in-time snapshot. Drift monitoring is what converts that snapshot into something you can detect regressions against — and it's the single biggest gap between a one-off audit deliverable and an ongoing retainer offering.

### What `/seo-drift` adds

The `seo-drift` skill (cherry-picked from claude-seo, installed at user level) captures a SHA-256-hashed baseline of 13 SEO-critical elements per URL: title, meta description, canonical, meta robots, H1/H2/H3 arrays, JSON-LD schema, Open Graph, Core Web Vitals (from PageSpeed Insights), HTTP status, and HTML/Schema content hashes. Storage is local SQLite at `~/.cache/claude-seo/drift/baselines.db`. Comparison applies **17 rules across 3 severity levels** (CRITICAL / WARNING / INFO) — e.g., a title length swing, an H1 disappearing, schema validation breaking, a canonical flip.

Why this matters that Squirrel Scan doesn't already cover: Squirrel Scan tells you what's broken *right now*. Drift tells you *what changed since last time* — at the per-element level, per URL. A quarterly Squirrel Scan rerun catches the cumulative state; drift catches the specific deployment that broke it.

### Setup and baseline verification

Use the complete shared script bundle and setup checks in the runbook §1 before capture (`--with-drift --seo-bundle "<bundle>"`). Run baseline and compare through that same managed runtime. A minimum verification is:

```bash
python "<bundle>/scripts/runtime.py" run drift_baseline.py <url> --skip-cwv
python "<bundle>/scripts/runtime.py" run drift_compare.py <url> --baseline-id <saved-id> --skip-cwv
```

Replace `<saved-id>` with the returned baseline ID. `--skip-cwv` is for this verification or unavailable performance evidence; it does not measure Core Web Vitals. Record any omitted performance evidence and preserve separately collected performance results. Require successful capture and comparison, a persisted baseline row in the reported SQLite database, and a comparison referencing that ID. Inspect the captured status/title/headings/canonical/schema against the page evidence; a successful exit with empty or wrong fields is not a valid baseline. Record the absolute database path, URL set, timestamp, baseline IDs, source revision, comparison result, and field coverage. Raw-response-only captures must be labelled as such; they cannot establish rendered coverage for JS-dependent pages. Preserve this initial snapshot, and add a separate post-fix baseline after implementation. If capture or comparison fails, mark drift unavailable with the repair action; do not silently substitute manual JSON and mark the step complete.

### Commands

| Command | Purpose | When to run |
|---|---|---|
| `/seo drift baseline <url>` | Capture current SEO state as a "known good" snapshot | End of audit (lock the post-fix state); before any planned deployment or migration; before publishing major content changes |
| `/seo drift compare <url>` | Diff current page state against the stored baseline | Monthly for retainer clients; after every production deployment if the client has frequent releases; on demand when ranking unexpectedly drops |
| `/seo drift history <url>` | Show change history for a URL across all captured baselines | Retrospectives ("when did the title change?"); ranking-drop investigations |

### When to run baseline capture in the audit flow

| Audit context | Baseline timing |
|---|---|
| **One-off audit (no retainer)** | Capture the initial snapshot at runbook §3.18 and hand over its database path, URL list, and repeat command. A retainer is not required to preserve a useful starting point. |
| **Retainer engagement starting** | Preserve the initial audit snapshot; add a separate baseline on the top 10-20 commercially important URLs *after* Tier 1 fixes ship, so the baseline represents the post-cleanup "known good" state. Label this later snapshot as post-fix; do not overwrite the initial evidence. |
| **Pre-migration** | Capture baseline of all top organic landing pages **on the current site** before launch. Post-launch `/seo drift compare` against pre-migration baseline surfaces every silent regression (lost canonicals, dropped schema, H1 changes). This is what turns "did the migration break anything we didn't notice?" from a manual diff into a one-command check. |
| **Pre-deployment (mature site with retainer)** | Optionally baseline before any significant template/theme/plugin change. Catches the page-builder-overwrites-canonical class of bugs. |

### Workflow for the monthly retainer check

1. `/seo drift compare <url>` against each baselined URL (script it as a batch if the client has 50+).
2. Triage: review CRITICAL findings promptly and agree any escalation with the client; WARNINGs roll up into the monthly report; INFOs are noise (review quarterly, suppress patterns that always fire).
3. For any CRITICAL or WARNING: judge whether the change was intentional (client published a new title — fine, re-baseline) or accidental (deploy stripped the schema — escalate to dev). The judgment call is the consultant value; the diff itself is just the trigger.
4. After intentional changes, re-baseline so future diffs compare against the new "known good."

### What drift does NOT replace

- **Rank tracking** — drift watches on-page state, not SERP position. Pair with whatever rank tracker the client already uses.
- **GSC monitoring** — drift doesn't see crawl errors or index status. Keep checking GSC.
- **Squirrel Scan** — drift watches 13 elements per URL; Squirrel Scan covers 230+ rules across 18 categories at site scale. Drift is the per-URL deployment watcher; Squirrel Scan is the quarterly full-site audit.
- **Content quality judgment** — a title that changes from good to bad still passes the "title length changed by <X%" rule. The skill diffs strings; you judge whether the new string is better.

### Dependency note

`seo-drift` also needs its shared Python scripts and dependencies verified. An existing PageSpeed key may help with API access, but a key does not guarantee quota. If performance requests return 429 and no measurement route is available, record that part of the comparison as unavailable; continue other comparisons without inventing performance changes.

### Why this stays consultant-driven

Resist the temptation to put `/seo drift compare` on a cron + email-alert hook. The 17-rule output will produce 10-30 findings per month per client across a typical URL set, and most will be either intentional changes or non-actionable noise. An autopilot setup floods the client with alerts and trains them to ignore the channel. The retainer value is *you* running the comparison, triaging the noise, and surfacing the 2-3 things per month that actually need action. Borrow the diff engine, keep the judgment manual.

---

## Report Design Philosophy

The biggest failure mode in SEO audits is writing a document that reads like a complete inventory of everything found. That produces "overwhelm syndrome" — the client sees 50+ findings, feels unable to start, and either shelves the report or asks you to prioritize it in a follow-up call. The goal is a document that reads like a decision memo: **here's what matters most and why, here's what to do first, here's everything else if you need it.**

**Right-size the report to the data you actually have.** Length is not value. The consultant is paid for prioritisation and impact, not word count — and a thin-data site deserves a thin report. When the numbers are small (a few hundred clicks, single-digit daily visitors, no keyword volumes pulled), resist inflating molehills into mountains to fill pages: no recurring narrative built on a one-day traffic blip, no seven-point content plan built on assumed volumes, no second summary restating the first. If the honest answer is "do these three things and re-measure in a month," that *is* the report. A tight two-page memo naming the three real levers beats a 30-page document burying them under speculation — and the client trusts it more. When you don't have the data, the right move is a shorter report plus a note on what to collect next, never a longer one. (Client feedback that prompted this rule: "we're not paid by the word, we're paid for impactful advice and prioritisation… don't make mountains out of molehills just to fill the pages.")

Three structural choices make the difference between a report that gets executed and one that gets archived.

### 1. The executive summary opens with the reframing finding, not a contents list

Most SEO executive summaries summarize what's in the report. That's the wrong job. The executive summary should do one thing: **reframe the client's assumptions about their own situation.**

A good executive summary:
- Opens with 1-2 findings that change how the client thinks about the problem. Not "we found 50 issues" — something like "the category keyword you should own ranks page 2 while your competitor owns the AI Overview" or "your Marketplace listing converts at half the rate of your own secondary listing."
- States what's working first, briefly. This establishes credibility and protects the client from feeling the report is an attack. One paragraph, not a list.
- Identifies the 2-3 findings that carry the most weight on everything else. These are the findings that restructure the priority order — not just "this is bad" but "this changes what we do first."
- Ends with a realistic net expectation for 90 days — not a list of everything that will improve, but a short honest paragraph about the most likely outcomes of doing the work. Include hedges where they belong (AI Overview behavior is volatile; Google re-evaluation takes 4-8 weeks; some changes depend on third parties). Clients remember what you promised.

**What to avoid:**
- Starting with methodology or scope. That belongs in the appendix.
- Listing all the findings as bullets. The executive summary is not a table of contents.
- False precision ("rankings will improve 30-40%"). If you can't back it up with the client's own data, don't say it.
- Burying the most important finding. The finding that reframes everything goes in paragraph one, not paragraph three.

**Prompt for Claude:** "Write an executive summary for this SEO audit. Open with the 1-2 findings that most change how the client should think about their SEO situation, not a list of everything found. State what's working in one paragraph. Then identify the findings that determine the priority order. Close with a realistic 90-day expectation with honest hedges. Data: [paste key findings]."

---

### 2. The 90-day plan is the spine of the report, not an appendix

The 90-day execution plan should appear on page 2, immediately after the executive summary. Not at the end. Not as an afterthought. It is the document's primary claim: **this is what you should actually do.**

Its job is to compress the entire report into a single page a stakeholder can act on without reading the rest. A good plan:

- **Uses actions, not findings.** "Fix the Thrive pagination bug" not "pagination 404s were found." The plan should read like instructions.
- **Groups by realistic execution window, not priority score.** Week 1, Month 1, This Quarter, and Deprioritized are more useful than Priority 1/2/3 — they answer "what do I do Monday morning?" rather than "what's theoretically most important?"
- **Includes a "Deprioritized for now" row.** This is critical. Explicitly naming what is NOT being done, and why, is as useful as naming what is. It prevents stakeholders from asking "but what about X?" for the next three months. The Deprioritized row says: we saw it, we considered it, we're deliberately not doing it yet.
- **Has no owner column.** The tool doesn't know the client's team or resources, so it must not invent assignees — a wrong "Dev/IT" label costs more credibility than it adds. The effort size signals whether an item is self-serve or a developer task; the reader assigns their own people.
- **Cites item numbers.** Cross-references to the detailed recommendations section let anyone who wants more context find it without the plan itself becoming long.

**Write the 90-day plan before you write the individual recommendations.** This is a sequencing discipline. If you write all 50 recommendations first and then try to distill them, you'll produce a plan that's just a shorter version of the full list. Writing the plan first forces genuine prioritization — you have to decide what actually matters before you document every finding.

After writing the plan, apply this filter to the full recommendations list: **if an item isn't in the 90-day plan, does it belong in the main report or in an appendix?** Items with a clear timeline and a concrete next action stay in the main report. Items that are exploratory, deferred, or dependent on data you don't yet have go to Phase 2 or the appendix.

---

### 3. The appendix is for noise, not just overflow

The standard consulting instinct is to put everything in the main report and summarize it in an appendix. This is backwards. The main report should contain only what informs a decision. Everything else — comprehensive findings, exploratory frameworks, detailed playbook templates, items deferred until more data is available — belongs in an appendix.

**What goes in the appendix:**
- Detailed pSEO playbook templates (the launch order table goes in the main report; the 5-page detailed breakdown of each cluster goes in the appendix)
- Full data source descriptions (a one-line reference in the main report is enough; the full table of what each source covered goes in the appendix)
- Comprehensive findings lists that document everything the tools found (useful for reference, not for decision-making)
- Items from the skills that are theoretically sound but not immediately actionable for this client
- Phase 2 / deferred items that need more data before they can be prioritized

**The test for what goes in the main report:** would a decision-maker reading this section change what they do or how they prioritize? If yes, it's main report content. If it's documentation of process, completeness, or exploratory analysis they might want later, it's an appendix.

**The practical result:** a well-structured audit has a main report of 20-25 pages that a stakeholder can read in 40 minutes and leave with a clear action plan, plus appendices of whatever depth is needed for implementation reference. The Apwide audit moved the 5 detailed pSEO playbooks (each with target URL structure, template requirements, and scale estimates) to Appendix B — they're valuable when building the content, but they're noise when deciding whether to build it at all.

**What this means for how you write with Claude:** when synthesizing skill outputs, explicitly ask Claude to separate "main report content" from "appendix material." The prompt: "From the following skill outputs, identify what belongs in the main prioritized recommendations and what belongs in an appendix because it's implementation detail rather than decision content: [paste skill outputs]."

---

### 4. Confidence calibration

A recurring failure mode in technical SEO audits is stating things more definitively than the evidence supports. Three patterns to watch for:

**Don't cite unofficial thresholds as if they were Google specifications.** Common examples: "Google's maximum of 100 internal links per page" (not a documented current limit), "Google's 1,500 DOM node threshold" (not how Google documents large DOM guidance), "meta descriptions must be exactly 155–160 characters" (a convention, not a specification). When these get challenged by a technical client, they undermine credibility for the whole document. State the principle without the false precision: "a DOM of 4,685 nodes is substantially above commonly recommended complexity levels" is defensible; "exceeds Google's 1,500 node threshold" is not.

**Use "consistent with" for patterns you can't confirm.** AI Overview suppression, crawl budget constraints, and Google's exact schema parsing behaviour are all things you can observe correlates of but cannot directly confirm from GSC data. "This pattern is consistent with AI Overview suppression" is accurate. "This is AI Overview suppression" is a causal claim you cannot make. The distinction matters when a technically literate client pushes back.

**Treat the change journal as context, not a causality machine.** A deployment and a ranking drop sharing a date strengthens an investigation hypothesis; it does not prove the deployment caused the drop. Separate preliminary from finalized GSC data, check Google-wide incidents and analytics changes, and look for a reproducible technical mechanism or a comparison group. Do not build seven-day ranking-only auto-rollback into an action.

**Soften absolute schema claims.** "Google rejects the entire JSON-LD block" is stronger than Google publicly documents — Google often extracts partial entity information even from invalid schema. The accurate framing: "the schema fails validation, likely preventing eligibility for rich results — Google may still extract some entity information but cannot reliably trust the structured data."

The practical test: before including a technical claim, ask whether you could defend it if a developer asked for the primary source. If the answer is "it's a widely-cited SEO convention," say so or soften the claim.

**Don't present derived numbers as platform totals.** The inselnova audit summed per-page impressions from the Pages CSV to report "~3,830 impressions" — a figure that didn't match what the client saw in GSC's own overview (130 clicks / 355 impressions for 28 days). Always quote the platform's headline number for the *exact date range you name*, and state the date range every time. If you must derive a figure, label it derived and show the working — never let a derived number masquerade as the source-of-truth total.

**Don't convert tiny absolute numbers into percentages.** "Daily clicks declined 69%" reads like a crisis; "went from ~8 clicks/day to ~3" is the honest version, and at that scale one post or a quiet week explains it. Below ~50 events, lead with absolutes and treat percentage swings as noise. Same rule for adjectives: the audit called impression growth "rapid" on pages that had 8–9 real visitors in 30 days. Match the adjective to the absolute number a stakeholder would actually see.

**Verify site facts against the live site before asserting them.** The audit claimed a 404 was "fixed" (it never existed — a prior report invented it), recommended adding internal linking and a docs index that already existed, and recommended an `llms.txt` that was already live. Open the page and check before you write "missing," "broken," or "fixed." And a partial crawl is not ground truth: squirrelscan behind Cloudflare prints "results may be incomplete" — caveat every score derived from an incomplete crawl, and never report a grade jump (55→60) as fact when the two crawls covered different page sets.

**Don't flag security findings carelessly—but do not ignore authoritative Google reports.** On a static site, crawler warnings for missing CSP/HSTS/X-Frame-Options headers are often irrelevant to an SEO priority list. GSC Security Issues and Manual Actions are different: check them explicitly and treat an affected result as authoritative Search evidence. Raise other security claims only when manually verified and relevant to the architecture.

**Don't manufacture crawl-budget work.** Record Crawl Stats, but below roughly 1,000 URLs with healthy discovery/host status and no direct constraint, server-log analysis is normally N/A. Even on a larger site, crawl-volume movement is not a diagnosis; require a material discovered backlog, host/response trouble, important-page recrawl lag, facet/parameter waste, migration, or another corroborating signal.

**Don't turn backlink-tool fear into a disavow action.** GSC, Ahrefs, and Bing observe different link samples/indexes, so their counts are not interchangeable. Google says most sites do not need disavow and misuse can hurt performance. A toxicity score or ugly domain is not enough; the exceptional route requires a considerable artificial-link pattern plus a Manual Action or credible link-scheme risk, expert review, and exact human approval.

**Don't overweight a one-off event.** The audit built a recurring narrative around a Hacker News "traffic bump" that was a 1–2 day blip over a month before the report and irrelevant by the time of writing. Separate the durable asset (the HN post still ranks #3 for the head term — a real backlink worth keeping) from the transient event (the traffic, long gone). Report the asset; drop the event.

---

### 5. SXO and drift findings — shape, placement, and the supersession pattern

The temptation when an SXO run completes is to drop the full skill output into the audit. The skill produces 7 dimensions of scoring, persona cards, prioritized actions, and limitations — easily 50-80 lines per URL analyzed. Doing that for 3-4 URLs bloats the report by hundreds of lines and reproduces the overwhelm failure mode that section 1 is designed to avoid. The Apwide audit went from 996 to 1,075 lines on the first pass (full skill output) and back down to 1,044 once trimmed — net ~50 lines for genuinely strategic findings, not ~150.

**What goes in the SXO section of the audit body** (~20 lines per URL analyzed):
- One-line setup: which URL, which keyword, when run
- The SERP composition table (top 8-10 with page-type column) — load-bearing evidence
- Verdict line: ALIGNED or MISMATCH (severity)
- Headline SXO Gap Score with the 2-3 weakest dimensions called out inline ("driven by missing BlogPosting schema, content depth below 2,000-word norm, E-E-A-T gaps") — *not* the full 7-row gap table
- "What this reframes" — bullet pointers to the audit items the SXO finding changes, with the new framing in one sentence per item. Actions live in the items themselves, not duplicated here.
- Limitations (WebSearch returned 8 not 10; no PAA; mobile vs desktop not separated; etc.)

**What does NOT go in the SXO section:**
- The full 7-dimension gap-score breakdown table — move to appendix only if the client asked for it; usually just cut
- Persona cards — only include if the personas actually drive a recommendation in the audit; usually they don't and the GSC query co-occurrence already implies them
- Priority actions as a numbered list — fold them into the items they affect (revised Item #N or new spoke under the pillar) so the action lives at the point of execution, not duplicated

**The supersession pattern — when SXO reframes an existing audit recommendation:**
SXO frequently disconfirms a hypothesis the original audit was building toward (Apwide: "we need a product page to rank for the head term" → SXO showed the SERP rewards blog explainers, not product pages). When this happens, follow this pattern in the audit body:

1. **Tag the affected item** with `*(revised YYYY-MM-DD per SXO analysis)*` in the heading.
2. **Rewrite the actions** to reflect the SXO-correct strategy.
3. **Preserve the original reasoning visible as superseded** at the end of the item, prefixed with `**Original recommendation (now superseded):**` and a one-line reason ("SXO disconfirmed the premise — see SXO Analysis section"). Don't delete the original. The reasoning trail tells future-you (and the client) what was considered and why it changed; deleting it makes you look like you flip-flopped.
4. **If the SXO finding reframes one of the executive summary's reframing findings**, update the exec summary opener sentence (one sentence rewrite — not a new paragraph). The exec summary is the most-read part of the doc; a contradiction between it and the body is the most damaging shape of inconsistency.
5. **Update Top Revenue Opportunities row mechanism description** if applicable, inline, with the SXO date tag.
6. **Do not add a new "Methodology Update" section above the 90-day plan to announce the SXO run.** The methodology update goes at the bottom or in Appendix A; the spine of the report stays on page 2.

**Drift baseline placement in the audit doc:**
Drift findings are forward-looking, not retro-applied. They show up in two specific places in the audit body:
1. **Week 1 end-of-week action** in the 90-Day Execution Plan: "After Tier 1 fixes ship, run `/seo drift baseline` on top 20 commercial URLs" — with the URL list explicit (homepage + top organic landing pages from GSC + top conversion landing pages from GA4 + key product/pricing pages).
2. **Verification & Tracking** section near the end of the report: `/seo drift baseline` listed as part of the baseline-snapshot step, and `/seo drift compare` as part of the monthly review cadence. Add the "don't put this on a cron with email alerts" guidance from Phase 4 verbatim.

That's the full drift footprint in the audit body. No drift findings inline elsewhere — there shouldn't be any at audit time.

---

### 6. Verify time-sensitive claims before delivery

Run [claim-check](https://skills.sh/BigChrisCooke/seo-playbook-skills/claim-check) on the final draft. It supports fact-checking, content freshness review, and SEO report QA by flagging prices, statistics, versions, product limits, deprecated features, search-engine claims, and missing or old verification dates.

For each finding, consult the primary source and record the URL and date actually checked. Confirm, correct, or remove the claim. Keep verification notes in `skills/claim-check.md` under the client audit folder, and put citations beside the claims they support in the report. Never add a checked-on date without checking the source.

The script identifies candidates for review; it does not browse the web or decide whether a claim is true. A clean scan is not a substitute for reviewing the evidence. [Install instructions](https://seo-audit-site.vercel.app/methodology/overview#install-the-playbook-skills) · [GitHub source](https://github.com/BigChrisCooke/seo-playbook-skills/tree/main/skills/claim-check).

---

## SEO Health Score

When all category inputs are available, the audit produces a single **0–100 SEO Health Score** at the top of the report, right after the title line. This serves two purposes: it gives stakeholders an instant baseline, and it makes re-running the audit compelling — "we went from 62 to 68" is a conversation starter.

The score is calculated by the AI during Phase 3 synthesis, not by an algorithm. The AI assigns a 0–100 score to each category based on the collected data, applies the weights below, and produces the weighted sum. This is a **consultant's assessment**, not a deterministic formula — it requires judgment.

### Scoring Framework (B2B SaaS)

| Category | Weight | What the AI evaluates |
|---|---|---|
| **Content Coverage** | 22% | Funnel coverage: does the site have TOFU, MOFU, and BOFU content mapped to the confirmed target persona? Thin-site penalty for low page count. Are the highest-intent pages (comparisons, integrations, alternatives) present? |
| **Technical SEO** | 20% | Squirrel Scan category scores aggregated: crawlability, indexability, security headers, URL structure, mobile, links. Normalise the Squirrel Scan overall score (which is already 0–100). |
| **On-Page SEO** | 18% | H1/title/meta completeness across key pages. Heading hierarchy correctness. Keyword-to-page mapping. Internal linking structure (spoke-to-hub, orphans). |
| **Performance** | 12% | PageSpeed Insights scores across top 3–5 pages (mobile). Core Web Vitals: LCP, TBT, CLS. Third-party bloat (CDN fonts, chat widgets, analytics). |
| **Schema Markup** | 10% | Schema validation pass rate. Missing required types per page type. @graph correctness. Domain consistency in @id fields. |
| **AI Visibility** | 10% | Fixed prompt benchmark coverage; observed brand mentions and client citations; recurring third-party cited domains; indexed, useful supporting pages; AI Overview/AI Mode appearance for validated target queries. Do not award points merely for `llms.txt` or "AI-specific" markup. |
| **Programmatic SEO** | 8% | Coverage of the five B2B SaaS playbooks: integrations, comparisons, personas, glossary, directory. Launch readiness of identified clusters. |

### Severity Tiers

| Tier | Score Range | Meaning |
|---|---|---|
| **Critical** | 0–39 | Major issues blocking indexing, rendering, or revenue. Requires immediate attention. |
| **High** | 40–59 | Significant problems impacting rankings or user experience. Fix within 1 week. |
| **Medium** | 60–79 | Optimization opportunities. Target within 1 month. |
| **Low** | 80–100 | Well-optimized site. Maintain and monitor. |

### Per-Category Breakdown

The score section in the report includes the overall score and a per-category breakdown so the client can see where the points are coming from — and where the biggest gains are:

```
## SEO Health Score: 62/100 (Medium)

| Category          | Score | Weight |
|-------------------|-------|--------|
| Content Coverage  | 45    | 22%    |
| Technical SEO     | 71    | 20%    |
| On-Page SEO       | 58    | 18%    |
| Performance       | 82    | 12%    |
| Schema Markup     | 40    | 10%    |
| AI Visibility     | 35    | 10%    |
| Programmatic SEO  | 55    | 8%     |

The two highest-impact levers are AI Visibility (35/100) and Schema Markup (40/100).
Together they account for 20% of the weighted score and are fixable within Week 1.
```

### Re-Run Tracking

The Verification & Tracking section (§12) should include a **score tracker** — a simple table showing the score at each audit cycle:

| Date | Score | Tier | Delta |
|---|---|---|---|
| 2026-06-01 | 62 | Medium | — (baseline) |
| 2026-06-15 | 68 | Medium | +6 |
| 2026-07-01 | 74 | Medium | +6 |

This is the single most effective retention mechanism in the report. It turns the audit from a one-off document into a recurring health check.

### Calibration Note

The AI must be honest about what the score means and does not mean:

- **The score is a consultant's assessment, not a Google ranking factor.** A score of 80 does not mean you'll rank #1. It means your site is well-optimized against the methodology's criteria.
- **Scores are not comparable across different sites.** A 62 for a 5-page SaaS site and a 62 for a 500-page publisher mean different things. Compare a site only against its own history.
- **Category scores can move independently.** Performance might drop (new feature added unoptimized scripts) while Content Coverage rises (new blog posts published). The overall score direction matters, but the category breakdown tells the real story.
- **Don't chase the number.** The score's job is to open the conversation, not end it. A site that improves schema validation and earns repeatable citations across the same commercial prompt benchmark has stronger evidence of progress than one that merely adds an unverified AI-facing file. Use the category breakdown, not just the overall.

---

## Report Structure Template

```
# [Client] SEO Audit & Prioritized Recommendations
Prepared: [date] | Scope: [scope] | Data sources: [1-line list with link to Appendix A]

## SEO Health Score: [0-100]/100 ([Tier])  ← page 1, right after title
Per-category table with scores and weights. Two sentences on the highest-impact levers.

## Leadership Summary          ← 60-second entry point; executives read this instead of the rest
Decisions required this week (3 max). Biggest commercial opportunity (1 sentence).
Core strategic observation about how the site is currently functioning vs. how it should.
What success looks like at 90 days — outcome framing, not a list of fixes.
NOT a summary of findings. NOT methodology. NOT a table of contents.

## Executive Summary
Opens with the 1-2 findings that reframe the client's situation. One paragraph on what's
working. The findings that determine priority order. Realistic 90-day expectation with hedges.
NOT a contents list. NOT methodology. 3-4 paragraphs maximum.

## 90-Day Execution Plan            ← page 2, not the end
Week 1 table: highest-risk / fastest-to-fix items
Month 1 table: highest-ROI items
This quarter: strategic content and authority building (bullet list)
Deprioritized for now: explicitly named items + reason (bullet list)

## Top Revenue Opportunities        ← elevates commercial findings before technical detail
5-row table: Priority / Opportunity / Why it's the top lever / Where in report

## Key Findings                     ← supports the executive summary with specifics
Performance & technical / Indexing / Traffic & conversion / Content lifecycle decisions / Backlink baseline / Historical SERP environment / SXO Analysis (if run). Include Crawl Stats only when it produces a useful verdict; keep detailed URL decisions in evidence/appendices. Include internal-search indexability under Indexing only when the conditional check produced a finding; report unsafe reflected input separately with the bounded-test caveat.
The SXO subsection sits inside Key Findings as a ~20-line block per URL analyzed — SERP table + verdict + headline score + "what this reframes" pointers + limitations. Full shape spec in Report Design Philosophy §5.

## Additional Findings from Skills  ← secondary layer; grounded in client data
One section per skill cluster; drop anything that isn't specific to this client

## Security & Platform Risk Findings ← OPTIONAL; default OMIT
Default to **omitting this section entirely.** Squirrel's security findings are noisy — it has flagged a LinkedIn share button as a credential leak, and "missing" CSP / X-Frame-Options headers are frequent false positives. SEO is not our security specialization; surfacing speculative security issues worries clients for no reason and damages credibility. Only include something if you've **manually verified it** and it actually affects crawling/indexing. When included, use the disclaimer close to verbatim: *"This is not a security audit tool and often raises false flags — check to verify before acting."* Never put security findings in Tier 1.

## What NOT to Do                   ← client-specific anti-patterns; prevents backsliding

## Prioritized Recommendations      ← single-layer, no duplicate matrix + detail structure
Each item: #N. Title / Impact / Effort / Issue / Actions / Verification (no Owner field — don't invent assignees)
Tier 1 → Tier 2 → Tier 3. Each item appears once.

## Programmatic SEO — Growth Initiatives
Launch order table only. "See Appendix B for full playbook detail." ← don't detail here

**Column headers must be exactly: `Month | Playbook | URL pattern | First batch | Quality bar`.** The Month column holds plain numbers — `1`, `2`, `3`, … — *not* "Wave 1 (Month 1)" or any other label. Multiple playbooks can share a month. Use `Defer` (not a number) for items pushed beyond the active plan.

## Phase 2 — Defer
Short bulleted list. Each item: what it is + why it needs more data before it can be prioritized.

## Content Standards                ← only if client is scaling pSEO content production

## Acquisition Channel Q&A          ← closing strategic section; answered LAST, from all sources
Goal framing: "turn this website into a predictable acquisition channel."
Explicit Q&A pairs for the runbook §5.7 questions (structure / conversion / product pages /
landing pages / lead magnets / SEO opportunities / content strategy + buyers-vs-traffic and
blog → lead magnet → demo/trial). Every answer cites data or names the gap + its Tier 1 action.
Ends with: website improvement roadmap, lead magnet plan, 6-month content priorities.

## Verification & Tracking
Baseline snapshot (capture via `/seo drift baseline` after Tier 1 fixes ship — see Phase 4)
Persistent change journal (action/deploy ID, timestamp, scope, target metric, acceptance result, Google incidents)
Monthly cadence (`/seo drift compare` on top 10-20 URLs; GSC + GA4 review; content lifecycle register; fixed historical SERP panel; backlink sample; rank tracker check)
Conditional Crawl Stats recheck; server logs only while a documented large-site/crawl-constraint question remains open
Content actions use approved evidence briefs and preserve Red approval for merge/prune/noindex/redirect decisions
For schema actions: live validator recheck, then same GSC Enhancement/Search Appearance comparison at 2/4/8 weeks; validity, eligibility, and display reported separately
90-day targets (hedged)

## From Audit to Action
Link to `./ACTION-RUNBOOK.md`, generated locally beside the report after report QA. Explain
that it was compiled from this report, classifies every recommendation by how the AI can
help, requires current best-practice research, manages approved batches, verifies live
changes, measures at 2/4/8 weeks, and preserves history across future audit cycles. Include
the exact start command from the audit runbook §5.2.

---

## Appendix A: Data Sources         ← full table of what was collected and when
## Appendix B: pSEO Detailed Playbooks  ← full templates, URL structures, scale estimates
## Appendix C: [Comprehensive findings list, if client wants it]
```

**The rule for the appendix:** if removing a section from the main report would prevent a stakeholder from making a good decision, it stays. If removing it would just mean they have to look something up later, it moves to the appendix.

**The single-home rule (anti-repetition).** Every fact and every recommendation appears in exactly one place. The inselnova Round 2 report stated the same `/inselkampf/` action and the same content thesis five times — Leadership Summary, Executive Summary, Top Revenue Opportunities, Content Plan, and Prioritized Recommendations. The client's verdict: "Repeated section. All of this is already included at least once above." Summaries and opportunity tables should *point* to the detailed item (by number), never restate it. If you're tempted to repeat a point "for emphasis," trust that the reader found it the first time — a report that says each thing once is a third the length and twice as credible. Two corollaries: (1) don't run a "Leadership Summary" *and* an "Executive Summary" that say the same thing — pick one, or make the second strictly additive; (2) don't title a section "Revenue" for a pre-revenue product — call it "Growth Opportunities" and match the client's actual stage.

---

## What to Adapt Per Client

These elements change for every client:

| Element | What to change |
|---|---|
| Top Revenue Opportunities | Find the client's actual conversion data first. For marketplace products: install/conversion rate. For SaaS with a trial: trial → paid rate. For lead-gen: demo request rate. The gap between the best-performing and worst-performing conversion touchpoint is usually the #1 revenue opportunity. |
| Security findings | **Default omit.** Squirrel is noisy here — it has flagged a LinkedIn share button as a credential leak. Include only if **manually verified** and it actually affects crawling/indexing. Never in Tier 1. Always with the *"not a security audit tool and often raises false flags — check to verify"* disclaimer. |
| Content cluster head term | The term the client *should* rank for but doesn't. Usually their own category name at page 2 or worse. |
| Competitor comparison Format 4 | Who are the top 2 incumbents in their specific category? The "third option" framing only works if the client is genuinely different (different platform, different segment, different pricing model). |
| pSEO integrations cluster | Only viable if the client has confirmed, real integrations with tools their customers already use. Confirm with the product team before recommending. |
| AI-search visibility | Check the live result before blaming an AI Overview for low CTR; CTR or anchor-fragment patterns alone do not prove the cause. Use the fixed persona-context benchmark to record the exact surface/date/locale, whether the client is mentioned or cited, and which domains recur. Improve content only where the underlying user task and independent demand support it, and pursue accurate third-party inclusion when those sources dominate. Do not recommend special AI files/schema or one page per prompt. |

---

## What Stays Consistent Across Clients

These patterns appear on almost every B2B SaaS site:

- **Default WordPress robots.txt** (just `/wp-admin/` blocked) — always needs expanding
- **Author archive and feed URLs consuming crawl budget** — almost universal
- **Thrive or Elementor theme pagination bugs** generating 404s — common
- **Schema present but invalid** — Organization.logo as object not string, missing publisher fields on Article
- **No comparison or alternative pages** — almost always absent
- **Internal nofollow links** — frequently misconfigured in page builders
- **Marketplace conversion gap and funnel invisibility** — for Atlassian/Shopify/Salesforce marketplace apps, the commercial conversion doesn't happen on the client's domain — it happens on the marketplace platform. The full acquisition funnel requires three separate GA4 configurations to become visible: (1) a GA4 key event on the website for outbound clicks to the marketplace listing, (2) a GA4 measurement ID added to the marketplace listing via the vendor portal (most platforms support this — e.g., Atlassian vendor dashboard → app settings → Analytics), and (3) cross-domain tracking in GA4 to stitch the website session and the listing session into one user journey. Without all three, the funnel from organic search to install is invisible. The marketplace Partner Portal (Atlassian, Shopify, Salesforce AppExchange) remains the authoritative source for install counts and revenue — GA4 cannot replicate that data. Cross-reference both monthly to calculate a visit-to-install rate.
- **Direct traffic anomaly in embedded software** — for any software that runs inside a third-party tool (Jira plugins, Salesforce apps, browser extensions, embedded iframes), the GA4 Direct channel often absorbs the software's own users accessing help pages from within the host app, where the referrer is stripped. These sessions typically show high bounce rate and under 10 seconds engagement — completely different behaviour from genuine direct visitors. Don't interpret a large Direct channel as brand awareness until the source is confirmed. See the GA4 checklist above for how to flag this during data collection.
- **Dev/localhost URLs in production HTML** — development environment URLs (localhost:8080, internal hostnames, staging CDN domains) appear in live production HTML on a surprising proportion of sites, especially those with a staging-to-production publishing workflow. Squirrel Scan flags these as broken external links — always inspect them. A localhost URL in production is both a broken link and a potential indicator that dev environment templates were promoted without sanitization.
- **Mobile performance drag from third-party scripts** — HubSpot, Intercom, Drift, Segment loaded on every page when only needed on 2-3 pages

---

## Prompting Tips

**Give each skill its own conversation turn.** Don't chain multiple skills in a single prompt — the outputs get mixed and it's harder to attribute which skill found what.

**Front-load data.** The more raw data you paste in, the more specific the output. A skill run against "it's a B2B SaaS" is generic. A skill run against pasted GSC data, PSI scores, and Squirrel Scan category scores produces findings that cite specific numbers.

**Explicitly say "apply this to my data"** not just "tell me about SEO for SaaS." The difference is the skill working as a framework applied to the client vs. the skill generating boilerplate advice.

**Run the seo-audit skill last** among the discovery skills. It catches gaps in everything else and often surfaces SaaS-specific issues the other skills don't flag. Running it first means you may not have enough context for it to be specific.

**Use Squirrel Scan output as a forcing function.** Paste the full XML output or the category scores + top failures into Claude alongside the skill prompt. The scan makes it nearly impossible for recommendations to be generic — every finding is grounded in a specific URL and rule ID.

---

## Known Gaps / Skills Roadmap

External review (2026-05) flagged eight capabilities this methodology didn't originally cover. Source repo for all of them: [AgriciDaniel/claude-seo](https://github.com/AgriciDaniel/claude-seo) (cloned to [apwide/temp-claude-seo/](apwide/temp-claude-seo/)). Status reflects what's actually installed at user level, not what could be installed.

| # | Capability | What it adds | Current substitute | Status (2026-05) |
|---|---|---|---|---|
| 1 | **seo-drift** | Baseline + diff for 13 SEO-critical elements (titles, canonicals, schema, CWV, HTTP, HTML/Schema hashes). 17 rules across 3 severity levels. SQLite history. Catches per-deployment regressions. | "Rerun Squirrel Scan quarterly" — far less granular | ✅ **Installed.** Cherry-picked from claude-seo into `~/.claude/skills/seo-drift/`. Documented in Phase 4 above. Requires `pip install beautifulsoup4 requests lxml validators` before first use. |
| 2 | **seo-sxo** | Page-type-vs-SERP-consensus analysis. Detects when a page format mismatches what Google rewards for a keyword (e.g. blog post targeting a query where the SERP is 8 product pages). Persona-based scoring, before/after wireframes. | Manual SERP captures (Phase 1) — observation only, no systematic scoring | **Optional; verify in your environment.** Requires the complete upstream shared scripts and runtime. A historical local installation is not proof of availability on a reader's machine. |
| 3 | **seo-backlinks** | Moz (DA/PA/spam) + Bing Webmaster (free competitor comparison) + Common Crawl (PageRank/in-degree) + verification crawler. Anchor text distribution, toxic link detection (30 patterns), competitor gap analysis. | Deferred to Phase 2 as "needs more data" | ⏳ Roadmap. Available in claude-seo source. Needs API keys (Moz, Bing Webmaster) + the heavier dep set. Install when first retainer client requests backlink reporting. |
| 4 | **seo-cluster** | SERP-based semantic topic clustering + content architecture planning. | `/site-architecture` covers internal architecture; nothing covers SERP-derived clustering | ⏳ Roadmap. Available in claude-seo source. Install when next building a content cluster from scratch — would replace manual SERP overlap analysis at the front of `/programmatic-seo`. |
| 5 | **seo-content-brief** | Competitive briefs with per-section word counts, competitor gap scoring, keyword density, page-type templates, E-E-A-T requirements. New-page and improve-existing-page modes. | None — falls to ad-hoc prompting | ⏳ Roadmap. Available in claude-seo source. Install when first commissioning a Tier 3 content build (briefs become the deliverable handoff to the writer). |
| 6 | **seo-hreflang** | International SEO: hreflang audit, cultural adaptation profiles, content parity checks. | None | ⏳ Out of niche. Available in claude-seo source. Skip unless a multi-locale client signs (Apwide is single-locale Atlassian Marketplace B2B). |
| 7 | **seo-ecommerce** | Product schema validation, marketplace intelligence, shopping feed optimization. | None | ⏳ Out of scope. Available in claude-seo source. Skip unless an ecommerce client signs. |
| 8 | **seo-flow** | FLOW framework (Find → Leverage → Optimize → Win) — 41 evidence-led AI prompts organized by SEO stage. | Implicit in this methodology doc | ⏳ Skip. This methodology *is* the FLOW layer for this niche. The skill's prompt library may surface individual prompts worth borrowing, but adopting the framework would duplicate work. |

**Bonus claude-seo skills not in the original review** (cloned but not installed; review per-need): `seo-competitor-pages`, `seo-content`, `seo-dataforseo`, `seo-geo`, `seo-google` (PDF/Excel report generator — avoid, autopilot shape), `seo-local`, `seo-maps`, `seo-page`, `seo-plan`, `seo-sitemap`, `seo-technical`, `seo-image-gen`, `seo-images`. Several overlap with coreyhaines31 skills already in use — do not install over the top.

`seo-schema` is worth reading as an additional deprecation checklist. Our published `schema-markup-better-than-corey-haines` now includes its own dated eligibility checks and primary-source references. Verify any third-party checklist against Search Central before recommending a rich-result type.

### Install procedure for additional claude-seo skills

Don't run claude-seo's full `install.ps1` — it would overwrite the existing Anthropic `seo` skill and pull in 25 skills, many of which collide with the coreyhaines31 versions the methodology depends on. Instead, cherry-pick:

1. Read the selected upstream release's installation instructions and keep the full repository available, including its root `scripts/` and requirements.
2. Install the selected skill without overwriting unrelated installed skills. Resolve its shared script paths explicitly; copying only `SKILL.md` and references is insufficient.
3. Follow the shared SXO/drift setup above. Run managed setup and doctor, then the checker with the applicable `--with-sxo` / `--with-drift` flags and explicit bundle root. Verify a rendered fetch and, for drift, an actual persisted baseline/compare before use.
4. Record the exact skill/script paths and source revision in this audit's preflight evidence. If incomplete, use the labelled manual fallback in §1 rather than declaring the skill installed.

### Positioning: why cherry-pick, not full install

claude-seo ([claude-seo.md](https://claude-seo.md/)) is built for heavy agent automation — multiple agents producing reports on autopilot, PDF/Excel exports, scheduled cron checks with email alerts. That's the wrong shape for this offering. The value of a manual consultant's audit in a known niche (B2B SaaS on Atlassian Marketplace, 6mo sales cycle, small TAM) is the human-in-the-loop reframing: choosing which finding goes in paragraph one of the Executive Summary, deciding what to deprioritize and why, calibrating confidence against what the data actually supports. An agent that writes a 50-finding report on autopilot reproduces the "overwhelm syndrome" failure mode the Report Design Philosophy section is explicitly designed to avoid.

The rule: **borrow data pipelines (drift baselines, SERP fetchers, backlink fetchers); keep report synthesis manual.** seo-sxo and seo-drift were installed because their pipeline output feeds back into consultant judgment — not because they generate the report themselves.

---

*End of methodology document.*