Google Search Console

Google Search Console — Data Interpretation and Diagnostics

Purpose

SYNTHEX connects to Google Search Console via OAuth to pull real search analytics, inspect URLs, manage sitemaps, and request indexing. This skill documents how to interpret the data GSC returns and how to diagnose common search visibility problems using Synthex infrastructure.

Infrastructure Map

API Routes (7):

Search Analytics Interpretation

Dimensions

getSearchAnalytics supports 5 dimensions: query, page, country, device, date. Default is ['query'] with 28-day range and 25-row limit.

Position Tiers and Actions

CTR Benchmarks by Position

Quick-Win Identification

Pattern: high impressions + low CTR relative to position

IF impressions > 500
  AND ctr < expected_ctr_for_position * 0.6
THEN
  Title tag or meta description needs improvement.
  Check: is title compelling? Does meta description contain a call to action?
  Check: are rich results (schema) available for this query type?

Pattern: position 4-10 with high impressions

IF position BETWEEN 4 AND 10
  AND impressions > 1000
THEN
  This query is achievable for page 1 top 3.
  Actions: expand content depth, add internal links, improve page speed.

Indexing Issue Decision Tree

URL not appearing in search?
  |
  +--> Run URL Inspection (checkIndexingStatus)
         |
         +--> indexingState = "INDEXED"
         |      --> Not an indexing issue. Check position via analytics.
         |      --> If position > 50: content quality or authority issue.
         |
         +--> indexingState = "DISCOVERED_NOT_INDEXED"
         |      --> Google found the URL but chose not to index it.
         |      --> Causes: thin content, low E-E-A-T signals, duplicate of stronger page.
         |      --> Fix: add unique value, demonstrate expertise, ensure canonical is correct.
         |
         +--> indexingState = "CRAWLED_NOT_INDEXED"
         |      --> Google crawled but deemed page low-value.
         |      --> Causes: duplicate content, low-quality pages, crawl budget waste.
         |      --> Fix: consolidate thin pages, improve content, add internal links.
         |
         +--> robotsTxtState = "BLOCKED"
         |      --> robots.txt is preventing crawling.
         |      --> Fix: update robots.txt to allow Googlebot access.
         |
         +--> pageFetchState = "SOFT_404"
         |      --> Server returns 200 but page looks like an error page to Google.
         |      --> Fix: return proper 404 status for missing pages, or add real content.
         |
         +--> pageFetchState = "SERVER_ERROR"
                --> Server returning 5xx errors.
                --> Fix: investigate server logs, ensure page loads reliably.

Coverage Report Interpretation

GSC coverage data comes from daily cron snapshots (gsc-monitor at 4 AM UTC). The getCoverageReport function returns aggregate counts from GSCSnapshot records.

Error Triage Protocol (in priority order)

1. Server errors (5xx) — highest priority; Google cannot access your pages at all
2. Redirect errors — broken redirect chains, loops, or redirects to 4xx pages
3. Soft 404s — pages returning 200 but appearing empty or error-like to Google
4. Blocked by robots.txt — unintentional blocks on important pages

Cross-Reference with Cron Alerts

The gsc-monitor cron creates notifications when:

• Click count drops >50% compared to the previous snapshot
• Coverage errors spike above baseline

When investigating a coverage alert, always check:

1. Which specific URLs are affected (drill into GSC UI or use URL Inspection)
2. Whether the issue correlates with a recent deploy (check git log)
3. Whether an algorithm update is active (invoke google-updates-sentinel skill)

Sitemap Strategy Checklist

Run through this checklist for any site connected to Synthex:

• Sitemap submitted to GSC? (listSitemaps returns empty = not submitted)
• Using sitemap index for large sites? (isSitemapsIndex flag)
• No errors or warnings? (errors === 0 && warnings === 0)
• Submitted count approximately equals indexed count? (large gap = quality issue)
• Auto-discovery via robots.txt? (robots.txt should contain Sitemap: https://...)
• Dynamic sitemap regenerates when new content is published?

Use submitSitemap(siteUrl, sitemapUrl) to submit or resubmit.

Indexing Request Best Practices

The Indexing API (requestIndexing) has strict limits:

• 200 requests per day per property (DAILY_QUOTA constant in gsc-auto-index cron)
• 600 URL Inspections per day (separate limit from Indexing API)
• Supports only URL_UPDATED and URL_DELETED notification types

When to use

• Newly published pages that need fast indexing
• Pages with significant content updates
• The gsc-auto-index cron automatically submits PlatformPost URLs that have publicUrl in metadata

When NOT to use

• Pages with noindex directive (wastes quota)
• Duplicate or thin content pages
• URLs that 404 or redirect
• Unchanged pages (Google will ignore and may rate-limit)

"Clicks Dropping" Diagnostic Tree

Clicks declining in GSC analytics?
  |
  +--> Check analytics trend (fetchAnalytics with dimensions: ['date'])
  |      Look for: gradual decline vs sudden drop
  |      Gradual: likely competitive or seasonal
  |      Sudden: likely technical or algorithmic
  |
  +--> Check for active algorithm rollout
  |      Invoke google-updates-sentinel skill
  |      If active rollout + traffic drop: follow type-specific recovery
  |
  +--> Check coverage errors (GSCSnapshot trends)
  |      Spike in errors = technical issue blocking crawling
  |
  +--> Check Core Web Vitals
  |      LCP > 2.5s, INP > 200ms, or CLS > 0.1 = ranking demotion risk
  |      Use SiteHealthSnapshot CWV data from Sentinel
  |
  +--> Check competitor activity
         Invoke competitive-local-strategy skill
         Competitor content surge can displace your rankings

Domain Knowledge

• GSC search analytics data has a 2-day lag — queries from today will not appear until ~48 hours later
• Position values are averaged across impressions, not clicks — a page showing at position 3 for 1,000 impressions and position 50 for 10 impressions averages to ~3.5
• URL Inspection results reflect Google's last crawl, not real-time state — the page may have changed since
• The getSearchAnalytics function defaults to type: 'web' — this excludes image, video, and news results
• GSC property URLs must match exactly — https://example.com and https://www.example.com are different properties
• OAuth token resolution follows a priority chain: explicit connectionId > org-level OAuth connection > service account fallback

Reference skill: This is a read-only architecture guide — it documents existing systems and does not generate creative or code output. No capability uplift block is needed.

Foundation & Gate Wiring (SYN-1049)

Adopted from the senior-skill standard so every artefact this connector produces is checked against the locked foundation before it lands.

Reads at every invocation (never cached — re-read each run):

• .claude/memory/ceo-foundation.md — verification gates for metric/traffic claims, universal taboos.
• .claude/memory/verification-gates.md — gate state for any claim referenced.

Output gate: every client-facing artefact this connector produces routes through brand-voice-enforce before the CEO batched-review queue. A REJECT blocks the artefact until the quoted offending string is fixed.

Evidence standard: every quantitative or factual claim carries exactly one tag — [VERIFIED] / [INFERENCE] / [UNCONFIRMED]. Untagged = defect (.claude/rules/fabel-evidence-standard.md). Never state a projected result as fact.

Spec: see spec.md in this skill directory.