> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synscribe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to fix a page that won't rank (or a ranking drop)

> Diagnose an underperforming page, keyword, or cluster by asking Pi to run the seo-debug skill — a structured observation, hypothesis, evidence, diagnosis walk that avoids defaulting to "must be backlinks" and writes a persistent report.

Ask Pi to run the **`seo-debug`** skill on the URL, keyword, or cluster: give it the observation
(what's wrong, on what surface, since when, by how much) and the expectation (what should be true and
why), and Pi walks a structured diagnosis — observation, then 2-4 hypotheses, then evidence per
hypothesis, then a differential diagnosis, then one specific next action — and saves a report to its `/memory/`. It is
built to *not* default to "must be backlinks": most issues are intent mismatches, technical breaks,
SOP misses, cannibalization, CTR regressions, or fresh-page jitter, and each hypothesis has to pass a
specific evidence gate before it survives into the diagnosis. You need GSC connected first
(see [2.1.3 Connect Google Search Console](/platform/connect-gsc)) — Pi debugs from data, not vibes.

> 🎬 **Video planned:** ask Pi to seo-debug a URL, read the hypothesis verdict table, pick the fix,
> re-check. See the shot-list.

## What Pi actually does

The skill runs an investigation, not a checklist:

1. **Capture observation + expectation.** Without both, it chases the wrong issue. It pulls the real
   numbers from GSC (clicks / impressions / avg position, period over period) rather than trusting
   the description.
2. **Verify the data before debugging the world.** Most "ranking dropped" tickets die here: was it
   actually published, is the slug what you think, is the rank data fresh, is the GSC "drop" real (it
   has a \~3-day lag)? If a data error explains it, that *is* the diagnosis.
3. **Form 2-4 hypotheses and commit a kill criterion for each** — from a library of ten patterns
   (fresh-page jitter, intent mismatch, cannibalization, technical break, SOP miss, competitive
   shift / link gap, manual action, seasonal drift, CTR regression, random fluctuation). It does not
   test all ten — it picks the most plausible given page age and cluster.
4. **Gather evidence per hypothesis against an explicit pass/fail gate.** Circumstantial evidence is
   rejected. "Multiple pages on the same topic exist" is not cannibalization; "two of your URLs share
   the same high-impression query in GSC" is. A comparable-DR competitor outranking you on
   *page-level* links is a valid link-gap finding; a DR-83-vs-DR-32 gap is a domain-authority moat,
   not an actionable link gap.
5. **Differential diagnosis.** Only CONFIRMED hypotheses (those that passed a gate) enter the
   diagnosis; the rest are explicitly REJECTED or marked INCONCLUSIVE. "Nothing is wrong" (fresh-page
   jitter, seasonal noise) is a valid, honest diagnosis — it won't manufacture an action item.
6. **One specific next action** with an owner and how to verify the fix, plus a saved report to
   `/memory/debug-<subject>-<orgId>-<date>.md` so the diagnosis is replicable.

## When each diagnosis sends you elsewhere

The skill hands off cleanly:

* **Intent mismatch or a domain-authority moat** leads to [SERP-cliff analysis](/platform/keyword-eval-vs-serp-cliff)
  to find a winnable sub-query, and routes any replacement keyword through
  [keyword evaluation](/platform/evaluate-serp-cliff).
* **SOP miss or technical break** leads to the deployment/technical checklist in
  [2.5.2 Technical SEO audit](/platform/technical-seo-audit); re-request indexing via
  [2.5.3 Index a URL + submit a sitemap](/platform/index-gsc-sitemap).
* **Confirmed comparable-DR link gap** — and only then — leads to [2.5.4 Link-building kickoff](/platform/link-building-kickoff).

## Real prompt

Give Pi the surface, the symptom, and what you expected — the more concrete the numbers, the sharper
the diagnosis:

```text theme={null}
this LP has been live 3 weeks on a soft SERP (cliff at 2) and should be on page 1,
but it's stuck around position 20. seo-debug [full URL] — figure out why and give me
one next action.
```

Pi confirms the page is really published and the rank data is fresh, pulls the GSC deltas, forms a
few hypotheses (here: intent mismatch, fresh-page jitter, cannibalization), tests each against its
gate, and returns a bottom-line-up-front verdict table, a one-sentence diagnosis, and a single
specific action — plus the path to the saved report.

For a drop rather than a never-ranked page, lead with the magnitude and the timeframe:

```text theme={null}
clicks on [full URL] are down ~40% over the last 28d vs the prior 28d and it held
position 4 for three months. what changed? run seo-debug and don't just tell me
"backlinks".
```

Because this is a sustained decline (position regressed materially over 30+ days), the skill is
*required* to run the SERP-cliff read and the competitor page-level backlink comparison before it
can close — so a link gap, if it's real, is proven with specific referring-domain numbers, not
asserted.

***

**Prerequisite:** [2.1.3 Connect GSC](/platform/connect-gsc) · **Sibling how-tos:** [2.8.2 Get cited by AI (fanout)](/platform/get-cited-by-ai) · [2.8.3 Bring your own DataForSEO key](/platform/byok-dataforseo) · **Sends you to:** [2.2.5 Keyword eval vs SERP-cliff](/platform/keyword-eval-vs-serp-cliff) · [2.5.2 Technical SEO audit](/platform/technical-seo-audit) · [2.5.4 Link-building kickoff](/platform/link-building-kickoff)