seo-traffic-diagnosis

$npx mdskill add rampstackco/claude-skills/seo-traffic-diagnosis

Diagnose organic traffic changes using Ahrefs MCP and Search Console data

  • Identifies why organic traffic moved (dropped, stalled, or unexpectedly increased) via root cause analysis.
  • Depends on Ahrefs MCP and Google Search Console data to diagnose issues post-update, migration, deploy, etc.
  • Uses a five-layer root cause analysis approach to determine the underlying causes of traffic changes.
  • Delivers a detailed diagnosis report and actionable recommendations directly to stakeholders or agents.

SKILL.md

.github/skills/seo-traffic-diagnosisView on GitHub ↗
---
name: seo-traffic-diagnosis
description: "Diagnose organic traffic changes (drops, stalls, or unexpected wins) using Ahrefs MCP plus Search Console data. Use this skill when traffic suddenly dropped, has been flat despite investment, after an algorithm update, after a migration or deploy, or when a competitor seems to be taking share. Triggers on traffic dropped, traffic decline, traffic stalled, organic decline, lost rankings, why is traffic down, algorithm update, post-migration traffic loss, traffic diagnosis. Also triggers when stakeholders are panicking about analytics."
category: seo-audit-suite
catalog_summary: "Diagnose drops, stalls, or wins via 5-layer root cause analysis"
display_order: 5
---

# SEO Traffic Diagnosis

Diagnose why organic traffic moved (down, flat, or unexpectedly up) using Ahrefs MCP combined with Search Console and analytics data. Stack-agnostic. Produces a root-cause diagnosis and an action plan.

---

## When to use

- Organic traffic dropped sharply
- Organic traffic has been flat for months despite content investment
- After a known Google algorithm update
- After a migration, replatform, or domain change
- After a deploy that touched routing, redirects, or rendering
- When a competitor is visibly taking organic share
- When a single page dropped from a ranked position
- When stakeholders need an explanation, fast

## When NOT to use

- Routine performance reporting (use `analytics-strategy`)
- Pre-emptive content planning (use `seo-content-gap-audit`)
- Backlink-only investigations (use `seo-backlink-audit`)
- Technical issue triage outside of traffic concerns (use `seo-site-health-audit`)

---

## Required inputs

- Description of the symptom (what changed, when, magnitude)
- Date the change started (best estimate)
- Recent SEO history: deploys, migrations, content changes, link campaigns
- Access to Ahrefs MCP, Search Console, and analytics
- Confirmation the change is real (not a tracking artifact)

---

## The framework: 5 layers of diagnosis

A traffic change has one or more root causes. Move through the layers in order. Stop when you have enough evidence.

### Layer 1: Confirm the change is real

Before diagnosing, rule out:

- Tracking gaps (analytics outages, tag manager issues)
- Bot traffic changes
- Reporting comparison errors (different date ranges, wrong segment)
- Seasonality (compare year-over-year, not just month-over-month)
- Holiday or weekday effects

Cross-check Search Console clicks against analytics organic sessions. Significant divergence often points to a tracking issue, not a real traffic change.

### Layer 2: Localize the change

Where is the change happening?

Segment by:

- Country and language
- Device (mobile, desktop, tablet)
- Page or section (homepage, blog, product, category)
- Query type (branded vs non-branded)
- Landing page

A change in one segment requires different diagnosis than a change everywhere.

| Pattern | Likely cause |
| --- | --- |
| One country dropped | Local algorithm update, hreflang issue, geo redirect issue |
| Mobile dropped, desktop flat | Mobile usability or page speed regression |
| One section dropped | Topical algorithm update or section-specific quality issue |
| Branded queries dropped | Brand-level issue: site outage, reputation, manual action |
| Non-branded dropped | Algorithmic ranking issue |
| Single page dropped | Page-level issue: content, technical, or competitive |
| Sitewide dropped | Sitewide issue: penalty, technical, migration, or algorithm |

### Layer 3: Page-level analysis

For affected pages, audit:

- Position changes per ranked keyword (Ahrefs Rank Tracker history)
- SERP composition changes (more ads, AI overviews, featured snippets, video)
- Click-through rate changes
- Index status (Search Console coverage)
- Crawl errors and accessibility
- Recent content changes
- Internal link changes
- Backlink changes (lost links, redirect chains)

A page can lose traffic without losing rank if SERP composition changed.

### Layer 4: Technical analysis

Did anything break technically?

Check:

- Robots.txt changes
- Canonical tag changes
- Meta robots changes (accidental noindex)
- Redirect chains and loops
- Render issues (especially for JS-heavy frameworks)
- Site speed regressions
- Hreflang errors
- Sitemap freshness
- HTTP status codes (4xx, 5xx spikes)
- Server log evidence of crawl behavior changes

Recent deploys are the prime suspect. Compare deploy dates to traffic change dates.

### Layer 5: External analysis

If layers 1-4 do not explain the change, look outward.

- Algorithm update calendar (cross-reference timing)
- Competitor moves (new content, new SERP features they captured)
- Industry trend (declining search demand for the topic)
- Manual action (Search Console security and manual actions)
- Negative SEO (sudden link velocity changes)

External-factor diagnosis benefits from competitive context: did your traffic drop while competitors held steady (suggests an algorithm-specific issue), or did the entire vertical lose ground (suggests a user-behavior shift)? Similarweb shows competitor traffic trends; Ahrefs shows competitor SERP movement; pairing both surfaces whether the issue is yours alone or the category's.

---

## Workflow

1. **Confirm the symptom.** Get exact dates, magnitude, segment if known.
2. **Validate the data.** Layer 1 checks. Rule out tracking and seasonality.
3. **Localize.** Layer 2. Segment until the pattern is clear.
4. **Page-level dive.** Layer 3 on the most affected pages.
5. **Technical check.** Layer 4. Recent deploys, robots, canonicals, redirects.
6. **External check.** Layer 5. Algorithm updates, competitors, industry.
7. **Build the hypothesis.** State the cause as a single sentence.
8. **Validate the hypothesis.** Find the evidence that confirms or refutes it. See [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md).
9. **Action plan.** Specific fixes mapped to specific evidence.
10. **Communicate.** Write up the diagnosis. Stakeholders want clarity, not exhaustive analysis.

---

## Failure patterns

- **Jumping to algorithm update.** "It must be the algorithm" is the lazy answer. Eliminate technical and page-level causes first.
- **Solving the wrong problem.** A drop diagnosed as "content quality" when the real cause was an accidental noindex on a deploy. Validate the hypothesis before fixing.
- **No baseline for "normal."** Without a baseline, every fluctuation looks alarming. Establish what normal noise looks like before reacting.
- **Treating one page as the site.** Site-wide and page-level diagnoses are different. Confirm scope first.
- **Ignoring branded vs non-branded.** A drop in branded queries means a brand-level problem. A drop in non-branded means an SEO problem. Different teams own them.
- **Comparing wrong date ranges.** Comparing 28 days to the previous 28 days during a holiday distorts the picture. Use year-over-year for seasonal businesses.
- **Stopping at correlation.** A deploy and a drop on the same day is a strong correlation, not proof. Find the mechanism.
- **Single-source diagnosis.** Ahrefs sees position. Search Console sees clicks and queries. Analytics sees behavior. Logs see crawl. Use them together.
- **Premature reassurance.** Telling stakeholders "it is just an algorithm update, will recover" without evidence sets up a worse conversation later.

---

## Output format

A diagnosis document with:

1. **Summary.** What changed, when, magnitude, root cause in one paragraph.
2. **The symptom.** Charts and segment breakdowns.
3. **Layer-by-layer findings.** What each layer ruled in or out.
4. **Root cause hypothesis.** Single statement with evidence.
5. **Action plan.** Ordered fixes with owners and timelines.
6. **Recovery forecast.** Realistic expectations on timeline and ceiling.
7. **Monitoring plan.** What to watch for confirmation of recovery.

Length: 4-10 pages. Stakeholders read this fast.

---

## Reference files

- [`references/diagnosis-checklist.md`](references/diagnosis-checklist.md) - Layer-by-layer diagnostic checklist with the specific data to pull at each layer and how to interpret each signal.

More from rampstackco/claude-skills

SkillDescription
ads-creative-developmentHow to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting.
ads-performance-analyticsHow to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue.
after-action-reportRun a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings.
ai-content-collaborationHow humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy.
analytics-strategyDesign measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track.
art-directionDirect visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables.
backup-and-disaster-recoveryPlan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability.
beta-program-managementRunning closed and open betas that produce real signal. Beta participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). Triggers on beta program, alpha test, beta cohort, beta participant, beta feedback, beta to GA decision, design partner, early access program, closed beta, open beta, RC release. Also triggers when a feature is approaching launch and the team needs structured pre-GA validation, when prior betas produced noise rather than signal, or when the team has soft-launched before but wants more structured feedback this time.
brand-archetype-systemApply pre-composed aesthetic archetype defaults to jumpstart brand design work covering color, typography, layout, voice, and imagery direction. Use this skill whenever the user wants a starting point for brand visual and verbal direction, references a brand they want to design near (for example 'something like Stripe' or 'editorial like Linear'), needs to converge faster from many directions to one, or wants known-good defaults for a specific industry vertical. Triggers on archetype, design archetype, brand archetype, near to (brand), in the style of, similar aesthetic, design starting point, brand template, vertical-typical, industry-typical. Also triggers when the user has a brief and wants to map it to a known aesthetic family rather than design from first principles.
brand-discoveryRun upstream brand discovery covering audience research, competitive landscape, category dynamics, problem space, and positioning territory exploration. Use this skill at the very start of a brand or website project when the user needs to understand who they're for, who they compete with, what the audience actually needs, and where the brand could plausibly stand. Triggers on brand discovery, audience research, market research, competitive scan, category research, customer research, who is this for, who are we, positioning research, intake, kickoff. Also triggers when a creative brief is requested but the upstream inputs (audience, competitors, problem space) are not yet clear.