seo-drift

SEO drift monitoring: capture baselines of SEO-critical elements, detect changes, and track regressions over time. Git for SEO: baseline, diff, and track changes to your on-page SEO. Use when user says "SEO drift", "baseline", "track changes", "did anything break", "SEO regression", "compare SEO", "before and after", "monitor SEO changes", or "deployment check".

SEO Drift Monitor (April 2026)

Git for your SEO. Capture baselines, detect regressions, track changes over time.

---

Commands

Command	Purpose
/seo drift baseline <url>	Capture current SEO state as a "known good" snapshot
/seo drift compare <url>	Compare current page state to stored baseline
/seo drift history <url>	Show change history and past comparisons

---

What It Captures

Every baseline records these SEO-critical elements:

Element	Field	Source
Title tag	title	seogeo parse
Meta description	meta_description	seogeo parse
Canonical URL	canonical	seogeo parse
Robots directives	meta_robots	seogeo parse
H1 headings	h1 (array)	seogeo parse
H2 headings	h2 (array)	seogeo parse
H3 headings	h3 (array)	seogeo parse
JSON-LD schema	schema (array)	seogeo parse
Open Graph tags	open_graph (dict)	seogeo parse
Core Web Vitals	cwv (dict)	seogeo pagespeed
HTTP status code	status_code	seogeo fetch
HTML content hash	html_hash (SHA-256)	Computed
Schema content hash	schema_hash (SHA-256)	Computed

---

How Comparison Works

The comparison engine applies 17 rules across 3 severity levels. Load references/comparison-rules.md for the full rule set with thresholds, recommended actions, and cross-skill references.

Severity Levels

Level	Meaning	Response Time
CRITICAL	SEO-breaking change, likely traffic loss	Immediate
WARNING	Potential impact, needs investigation	Within 1 week
INFO	Awareness only, may be intentional	Review at convenience

---

Storage

All data is stored locally in SQLite:

text

~/.cache/seo-geo-skill/drift/baselines.db

Tables

• baselines: Captured snapshots with all SEO elements
• comparisons: Diff results with triggered rules and severities

URL normalization ensures consistent matching: lowercase scheme/host, strip default ports (80/443), sort query parameters, remove UTM parameters, strip trailing slashes.

---

Command: baseline

Captures the current state of a page and stores it.

Steps:

1. Validate URL (SSRF protection via google_auth.validate_url())
2. Fetch page via seogeo fetch
3. Parse HTML via seogeo parse
4. Optionally fetch CWV via seogeo pagespeed (use --skip-cwv to skip)
5. Hash HTML body and schema content (SHA-256)
6. Store snapshot in SQLite

Execution:

bash

seogeo drift baseline <url>
seogeo drift baseline <url> --skip-cwv

Output: JSON with baseline ID, timestamp, URL, and summary of captured elements.

---

Command: compare

Fetches the current page state and diffs it against the most recent baseline.

Steps:

1. Validate URL
2. Load most recent baseline from SQLite (or specific --baseline-id)
3. Fetch and parse current page state
4. Run all 17 comparison rules
5. Classify findings by severity
6. Store comparison result
7. Output JSON diff report

Execution:

bash

seogeo drift compare <url>
seogeo drift compare <url> --baseline-id 5
seogeo drift compare <url> --skip-cwv

Output: JSON with all triggered rules, old/new values, severity, and actions.

After comparison, offer to generate an HTML report:

bash

seogeo drift report <comparison_json_file> --output drift-report.html

---

Command: history

Shows all baselines and comparisons for a URL.

Execution:

bash

seogeo drift history <url>
seogeo drift history <url> --limit 10

Output: JSON array of baselines (newest first) with timestamps and comparison summaries.

---

Cross-Skill Integration

When drift is detected, recommend the appropriate specialized skill:

Finding	Recommendation
Schema removed or modified	Run /seo schema <url> for full validation
CWV regression	Run /seo technical <url> for performance audit
Title or meta description changed	Run /seo page <url> for content analysis
Canonical changed or removed	Run /seo technical <url> for indexability check
Noindex added	Run /seo technical <url> for crawlability audit
H1/heading structure changed	Run /seo content <url> for E-E-A-T review
OG tags removed	Run /seo page <url> for social sharing analysis
Status code changed to error	Run /seo technical <url> for full diagnostics

---

Error Handling

Scenario	Action
URL unreachable	Report error from seogeo fetch. Do not guess state. Suggest user verify URL.
No baseline exists for URL	Inform user and suggest running baseline first.
SSRF blocked (private IP)	Report validate_url() rejection. Never bypass.
SQLite database missing	Auto-create on first use. No error.
CWV fetch fails (no API key)	Store null for CWV fields. Skip CWV rules during comparison.
Page returns 4xx/5xx	Still capture as baseline (status code IS a tracked field).
Multiple baselines exist	Use most recent unless --baseline-id specified.

---

Security

• All URL fetching goes through seogeo fetch which enforces SSRF protection (blocks private IPs, loopback, reserved ranges, GCP metadata endpoints)
• No curl, no subprocess HTTP calls -- only the project's validated fetch pipeline
• All SQLite queries use parameterized placeholders (?), never string interpolation
• TLS always verified -- no verify=False anywhere in the pipeline

---

Typical Workflows

Pre/Post Deployment Check

text

/seo drift baseline https://example.com     # Before deploy
# ... deploy happens ...
/seo drift compare https://example.com      # After deploy

Ongoing Monitoring

text

/seo drift baseline https://example.com     # Initial capture
# ... weeks later ...
/seo drift compare https://example.com      # Check for drift
/seo drift history https://example.com      # Review all changes

Investigating a Traffic Drop

text

/seo drift compare https://example.com      # What changed?
/seo drift history https://example.com      # When did it change?