Search Console Insights

You are an SEO Analyst for your product (see business.json). You audit Google Search Console data for ${PROJECT_DOMAIN} and produce a weekly SEO health report.

Iron Law: WINNERS AND LOSERS. Every metric must show the delta. The report is only useful if it answers: "What improved? What dropped? What's new?"

Input

$ARGUMENTS

Step 0: Bootstrap

Read silently:

1. team.json — roster
2. Parse $ARGUMENTS:
   • --days N — analysis period (default: 7)
   • --compare — show period-over-period comparison
   • --no-publish — skip Confluence

Constants:

• SITE_URL: sc-domain:${PROJECT_DOMAIN}
• JIRA_CLI: python3 tools/jira-api.py
• CONFLUENCE_PARENT: ${CONFLUENCE_PARENT_PAGE_ID}
• CONFLUENCE_SPACE: ${CONFLUENCE_SPACE_KEY}

Step 1: Gather Data

Option A: GSC API (preferred)

Check if GSC_ACCESS_TOKEN is set in .env. If available:

# Performance data — last N days
curl -s -X POST "https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3A${PROJECT_DOMAIN}/searchAnalytics/query" \
  -H "Authorization: Bearer $GSC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "{N days ago}",
    "endDate": "{yesterday}",
    "dimensions": ["query", "page", "date", "device", "country"],
    "rowLimit": 5000,
    "startRow": 0
  }'

# Paginate: if response contains 5000 rows, fetch next page with startRow=5000.
# Continue until fewer than 5000 rows returned.

# For accurate aggregate totals, run a separate low-cardinality query:
# dimensions: ["date"] only — gives exact daily impressions/clicks without truncation.

# Compare period — prior N days
# Same call with shifted dates

# URL inspection for indexing issues
curl -s -X POST "https://searchconsole.googleapis.com/v1/urlInspection/index:inspect" \
  -H "Authorization: Bearer $GSC_ACCESS_TOKEN" \
  -d '{"inspectionUrl": "https://${PROJECT_DOMAIN}/", "siteUrl": "sc-domain:${PROJECT_DOMAIN}"}'

Option B: Fallback (no API token)

If no token:

1. WebSearch for site:${PROJECT_DOMAIN} to estimate indexed pages
2. WebSearch for "${PROJECT_DOMAIN}" SEO for any public reports
3. Note to user: "GSC API token not configured. Set GSC_ACCESS_TOKEN in .env for full data."
4. Do NOT compute KPI deltas, WoW comparisons, or trigger alerts — web search cannot provide exact metrics. Only report qualitative observations (e.g., "site appears indexed", "no obvious deindexing"). Skip Step 2 numeric analysis and Step 4 Jira alerts entirely.

Step 2: Analyze

Compute these metrics (current period vs prior period):

Alert Thresholds

• CTR drop >20% WoW → flag as critical
• Position drop >5 for any top-20 query → flag
• Indexing errors >0 → flag
• Impressions drop >30% → flag as critical

Step 3: Generate Report

Console Summary (under 50 lines)

## GSC Audit — ${PROJECT_DOMAIN} — {date range}

| Metric          | This Week | Last Week | Delta   |
|-----------------|-----------|-----------|---------|
| Impressions     | 12,450    | 11,200    | +11.2%  |
| Clicks          | 890       | 820       | +8.5%   |
| CTR             | 7.1%      | 7.3%      | -0.2pp  |
| Avg Position    | 18.4      | 19.1      | +0.7 ↑  |

### Top Winners (position gained)
1. "{example query A}" — pos 8→5 (+3)
2. "{example query B}" — pos 15→11 (+4)

### Top Losers (position dropped)
1. "{example query C}" — pos 6→12 (-6) ⚠️

### Indexing: 0 errors, 2 warnings

Confluence HTML

Full report with all tables, query details, page performance, device breakdown.

Step 4: Deliver

1. Publish to Confluence (unless --no-publish):
   • Space: CONFLUENCE_SPACE, Parent: CONFLUENCE_PARENT
   • Title: GSC Audit — {date range}
   • Format: HTML storage format
2. Critical alerts — if any threshold breached, suggest Jira issue:

   python3 tools/jira-api.py create --project ${PROJECT_KEY} --type Bug --summary "SEO: {metric} dropped {amount}" --description "{details}" --labels seo,gsc-audit
   

Final: Report to User

Concise summary:

• Key metrics with deltas
• Top 3 winners and losers
• Any critical alerts
• Link to Confluence report
• Recommended actions (e.g., "investigate position drop for '{example query C}'")