Open-source SEO, GEO, and marketing skills for AI agents.
feat(seo-analysis): priority-first report and audit history log (#28)
Tong Chen8938333da325
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 56259e50..1d81391e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,17 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).---+## [0.9.4] — 2026-04-07++### Changed+- **`seo-analysis` report restructured for clarity** — Phase 6 now leads with "Top Priority Actions" (3–5 items, ordered by expected click impact) instead of 12+ equal-weight sections. Each action requires a specific URL, specific metric as evidence, and a copy-paste-ready fix with estimated click impact. Supporting data (indexing issues, cannibalization, gaps, schema, technical) is condensed into reference tables shown only when findings exist.+- **`seo-analysis` audit history tracking** — new Step 0.5 reads `~/.toprank/audit-log/<domain>.json` at startup to surface previously flagged issues and their current resolution status. New Phase 6.5 writes a concise log entry after each audit (date, traffic snapshot, top issues with metrics and expected impact). Future audits show which prior issues are resolved, improved, or still open.++### Fixed+- **`seo-analysis` Phase 3.7** — removed duplicate `$DOMAIN` extraction; now reuses the variable set in Step 0.5 instead of re-deriving it.++---+## [0.9.3] — 2026-04-07### Addeddiff --git a/VERSION b/VERSIONindex 965065db..a602fc9e 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.9.3+0.9.4diff --git a/seo/seo-analysis/SKILL.md b/seo/seo-analysis/SKILL.mdindex 6276f2f4..e6b831d4 100644--- a/seo/seo-analysis/SKILL.md+++ b/seo/seo-analysis/SKILL.md@@ -87,6 +87,30 @@ user-provided URL.---+## Step 0.5 — Load Audit History++After identifying `$TARGET_URL`, derive the domain (used throughout the entire audit) and check for a previous audit log:++```bash+DOMAIN=$(python3 -c "import sys; from urllib.parse import urlparse; print(urlparse(sys.argv[1]).netloc.lstrip('www.'))" "$TARGET_URL")+AUDIT_LOG="$HOME/.toprank/audit-log/${DOMAIN}.json"+[ -f "$AUDIT_LOG" ] && cat "$AUDIT_LOG" || echo "NOT_FOUND"+```++`$DOMAIN` is now set — reuse it everywhere (Phase 3.7, Phase 6.5). Do not re-derive it.++**If found**: Extract the most recent entry's `date` and `top_issues`. Show the user a brief one-liner:++> "Last audit: [date]. Previously flagged: [issue #1 title], [issue #2 title]. I'll check whether these are resolved."++Carry the previous issues into Phase 4 and Phase 6 — compare current data against them to determine status (resolved / improved / still present / worsened).++**If not found**: This is the first audit. No action needed.++Do NOT pause for user confirmation — just show the one-liner and continue.++---+## Phase 0 — Preflight CheckRead and follow `../shared/preamble.md` — it handles script discovery, gcloud auth, and GSC API setup. If credentials are already cached, this is instant.@@ -399,12 +423,11 @@ reveal what real visitors search for, in their own words.### Check for cached personasPersonas are cached at `~/.toprank/personas/` keyed by domain hostname. Check-whether a persona file already exists:+whether a persona file already exists (`$DOMAIN` is already set from Step 0.5):```bash-DOMAIN=$(python3 -c "import sys; from urllib.parse import urlparse; print(urlparse(sys.argv[1]).netloc.lstrip('www.'))" "$TARGET_URL")PERSONA_FILE="$HOME/.toprank/personas/$DOMAIN.json"-[ -f "$PERSONA_FILE" ] && echo "FOUND" && cat "$PERSONA_FILE" || echo "NOT_FOUND"+[ -f "$PERSONA_FILE" ] && cat "$PERSONA_FILE" || echo "NOT_FOUND"```**If found and `saved_at` is less than 90 days old**: Show a one-line summary of@@ -892,194 +915,167 @@ After presenting the schema audit, offer:## Phase 6 — Report-Output a structured report. Use this format exactly:-------# SEO Analysis Report — [site.com]-*Analyzed: [date range] | Data: Google Search Console + URL Inspection + Technical Crawl*--## Business Profile-*(From Phase 3.8 — provides goal and competitive context for all recommendations below)*--**[Business Name]** — [business_summary from context]-- **Primary goal**: [primary_goal]-- **Target audience**: [target_audience]-- **Competitors tracked**: [competitors list, or "none provided"]--## Audience Personas-*(From Phase 3.7 — drives all recommendations below)*--| Persona | Primary Goal | Key Search Language | Decision Trigger |-|---------|-------------|---------------------|-----------------|-| [Persona 1 name] | [goal] | [language samples] | [trigger] |-| [Persona 2 name] | [goal] | [language samples] | [trigger] |-| [Persona 3 name if applicable] | | | |+**The goal of this report is not comprehensiveness — it is clarity.** The user needs to know exactly what to do next, in what order, and why. Lead with the highest-impact actions. Put supporting data after. Omit anything that doesn't change what the user should do.-## Executive Summary-[2-3 sentences: overall health, the single most important thing to fix, and the-estimated opportunity if fixed. Be specific: "Your site gets 12,400 clicks/month-but is leaving an estimated 3,000-5,000 additional clicks on the table from-position 4-10 queries that need title tag optimization. The primary audience —-[Persona 1 name] — searches using [language] but current titles use [different-language], which is suppressing CTR."]+Output a structured report using this format exactly:-## Traffic Snapshot+----| Metric | Value | vs Prior Period |-|--------|-------|----------------|-| Total Clicks | X | up/down X% |-| Impressions | X | up/down X% |-| Avg CTR | X% | up/down |-| Avg Position | X | up/down |+# SEO Report — [site.com]+*[date] · GSC data: [date range] · [First audit / Previous audit: date]*-## Branded vs Non-Branded Split-*(omit this section if brand terms were not provided)*-| Segment | Queries | Clicks | Impressions | CTR | Avg Position |-|---------|---------|--------|-------------|-----|--------------|-| Branded | X | X | X | X% | X |-| Non-branded | X | X | X | X% | X |+## Audit History+*(Skip this section entirely on the first audit — do not write "N/A" or "First audit" here; just omit the section.)*-[1-2 sentence interpretation: what the split reveals about brand vs organic performance]+On subsequent audits, show only what changed from the previous audit's top issues:-## Traffic by Site Section-| Section | Pages | Clicks | CTR | Avg Position | Notes |-|---------|-------|--------|-----|--------------|-------|-| /blog/ | X | X | X% | X | |-| /products/ | X | X | X% | X | |-| other | X | X | X% | X | |+| Previously Flagged | Status | Notes |+|--------------------|--------|-------|+| [Issue from last audit] | ✅ Resolved / ⚠️ Improved / 🔴 Still present / ↗ Worsened | [1-line update with current metric] |-[Flag any section with CTR significantly below site average — likely a template problem]+----## Quick Wins (Fix These First)+## ⚡ Top Priority Actions-[Numbered list, most impactful first. Every recommendation must include:-1. The specific page URL-2. The specific query/keyword-3. Current metrics (position, impressions, CTR)-4. What to change (exact new title, description, or action)-5. Why this will work (the search intent logic)]+This is the core of the report. Include exactly 3–5 items, ordered by expected click impact. Every item must have a specific URL, a specific metric as evidence, and a specific fix — nothing generic.-Example format: "Update title tag on /pricing from 'Pricing' to 'Plans &-Pricing — [Actual Value Prop]' — currently ranks #7 for 'your-product pricing'-with 2,400 monthly impressions but only 1.2% CTR. This is a transactional query-likely searched by [Persona name] who uses phrases like '[persona language]'.-The current title does not match their vocabulary or signal the outcome they-want. A title written in their language — '[example title]' — would increase-CTR to ~3-5%."+Use this format for each:-Every persona-informed recommendation must name the persona and include the-specific language from that persona's profile that should appear in the rewrite.+----## URL Inspection Findings+**#1 — [Short title, e.g. "Fix title tag on /pricing"]**+🔴 Critical / 🟡 High / 🟢 Medium+**Impact**: ~+[N] clicks/mo · **Effort**: Low / Med / High-[Results from Phase 3.5. Tables grouped by severity:]+**What**: [One sentence describing the problem]+**Evidence**: [Exact metric — e.g., "ranks #7 for 'your-product pricing': 2,400 impressions/mo, 1.2% CTR (expected ~3% at this position)"]+**Fix**: [Specific, copy-paste-ready action — e.g., "Change title from 'Pricing' to 'Plans & Pricing — [Value Prop] | [Brand]' (54 chars)"]+**Why it works**: [One sentence on the mechanism — intent match, persona language, etc.]-### Critical: Not Indexed-| Page URL | Coverage State | Last Crawl | Root Cause | Fix |-|----------|---------------|------------|------------|-----|+----### Warnings: Mobile / Rich Result Issues-| Page URL | Issue | Impact | Fix |-|----------|-------|--------|-----|+Repeat for each of the 3–5 items. Do not add a 6th item — triage ruthlessly. An item only makes the list if you can quantify its impact.-### Crawl Staleness-[Pages with last crawl > 60 days despite having traffic, with hypothesis and fix.]+When estimating impact, use conservative CTR curves: position 1 ~27%, position 2 ~15%, position 3 ~11%, position 4–5 ~5–8%, position 6–10 ~2–4%. Moving from position 7 to 3 on a 2,400 impression/month query means roughly +170 clicks/month. Always use real numbers from the data.-## Search Intent Mismatches-[Pages where the content type does not match what searchers want. For each: the-query, the current page, the intent, and what to do about it.]+Every persona-informed recommendation must name the persona and cite the specific language from that persona's `language` field that should appear in the rewrite.-## Keyword Cannibalization-[Queries where multiple pages compete. Which page should win, what to do with-the others.]+----## Keyword Gaps+## Traffic Snapshot-### Orphan Keywords (Rankings Without Dedicated Pages)-| Query | Ranking Page | Position | Monthly Impressions | Recommended Action |-|-------|-------------|----------|---------------------|--------------------|+| Metric | Value | vs Prior 28 days |+|--------|-------|-----------------|+| Total Clicks | X | ↑/↓ X% |+| Impressions | X | ↑/↓ X% |+| Avg CTR | X% | ↑/↓ |+| Avg Position | X | ↑/↓ |-### Topic Clusters Needing Pillar Pages-[Each cluster with constituent queries, impressions, and pillar page recommendation.]+*(Branded/non-branded split — only if brand terms were provided):*+| Segment | Clicks | Impressions | CTR | Avg Position |+|---------|--------|-------------|-----|--------------|+| Branded | X | X | X% | X |+| Non-branded | X | X | X% | X |-### Business Relevance Gaps-[Topics the site should rank for based on what it does, but has zero/near-zero-impressions for. Specific, not generic.]+[1-sentence interpretation of the split — what it reveals about organic vs brand performance]-## Metadata Issues+----| Page URL | Issue Type | Current Value | Target Persona | Recommended Fix |-|----------|-----------|---------------|----------------|-----------------|-| /example | Title too generic | "Services" | [Persona name] | "[Keyword in their language] Services — [Benefit they care about] \| [Brand]" |-| /pricing | No meta description | — | [Persona name] | Write 150-160 char description using "[their vocabulary]" and addressing "[their goal]" |+## Supporting Findings-Each metadata fix must use the target persona's vocabulary and address their-primary goal. Generic titles like "Services" or "Solutions" fail because they-don't match any persona's search language — replace with the exact terms from-the persona's `language` field.+This section exists to back up the Priority Actions and surface anything else the user should know. Keep it concise — tables and short bullets, not prose paragraphs. Only include sub-sections where there are actual findings.-## Schema Gaps+### Indexing Issues+*(From Phase 3.5. Only include if issues found.)*+| Page | Coverage State | Last Crawl | Fix |+|------|---------------|------------|-----|-| Page URL | Site Type | Missing Schema | Impact | Priority |-|----------|-----------|---------------|--------|----------|-| / | SaaS | FAQPage | High — FAQ rich results expand SERP footprint | P1 |-| /pricing | SaaS | Offer, AggregateRating | High — pricing rich results increase CTR | P1 |+### Keyword Cannibalization+*(Only include if `cannibalization` data is non-empty.)*+| Query | Winner Page | Loser Pages | Action |+|-------|------------|-------------|--------|-### Existing Schema Errors-| Page URL | Schema Type | Error | Fix |-|----------|------------|-------|-----|+### Content Gaps+*(Queries ranking 11–30 with >200 impressions and no dedicated page.)*+| Query | Position | Impressions/mo | Recommended Action |+|-------|----------|---------------|--------------------|++### Metadata Issues+*(Only pages not already covered in Priority Actions.)*+| Page | Issue | Current | Recommended Fix |+|------|-------|---------|-----------------|++### Schema Gaps+*(High-impact missing schema for this site type.)*+| Page | Missing | Impact |+|------|---------|--------|++### Technical Issues+*(Severity: Critical / High / Medium. Omit Low unless they surface as Priority Actions.)*+| Issue | Pages Affected | Fix | Severity |+|-------|---------------|-----|----------|++### Traffic Drops+*(Pages/queries with >30% decline. Only include if not already in Priority Actions.)*+| Page / Query | Change | Hypothesis | Next Step |+|-------------|--------|------------|-----------|++### CMS SEO Audit+*(Only if a CMS is configured. Top 5 impactful fixes only.)*+| Page | Issue | Current | Fix |+|------|-------|---------|-----|-## Content Opportunities-[Topic clusters you partially rank for that need dedicated pages or expanded-content. Group by theme, suggest page titles, target keywords.]+----## Traffic Drops to Investigate-[Pages/queries with significant declines, with a hypothesis and investigation-steps for each.]+## What to Ignore (For Now)+List 2–3 things the data shows but that don't make the priority list — so the user knows you saw them and deprioritized them deliberately. One line each.-## Technical Issues-[Severity: Critical / High / Medium / Low]-[For each: what it is, which pages, how to fix it, and the impact on rankings-if left unfixed.]+- [e.g., "Device split: mobile CTR 15% below desktop — worth watching but not the bottleneck right now"]+- [e.g., "Country split: weak CTR in UK — low volume, investigate after core issues fixed"]-## CMS SEO Field Audit-*(Only included when a CMS is configured — WordPress, Strapi, Contentful, or Ghost.)*+----| Issue | Count | Top Affected Pages |-|-------|-------|--------------------|-| Missing meta title | X | slug-1, slug-2... |-| Missing meta description | X | ... |-| Meta title too long (>60 chars) | X | ... |-| Meta description out of range | X | ... |+After the report, write the audit log entry (see Phase 6.5 below before ending).-**Highest-impact fixes** (pages with most GSC impressions + missing/bad SEO fields):-[List 5 specific pages: current meta title → recommended meta title, with character counts]+----*(For Strapi: "I can push these fixes directly — run `push_strapi_seo.py` after approval.")*+## Phase 6.5 — Write Audit Log-## 30-Day Action Plan+After delivering the report, append a concise entry to the audit log. `$DOMAIN` and `$AUDIT_LOG` are already set from Step 0.5.-[Prioritized by impact. Each item must be specific enough that someone could do-it without asking follow-up questions.]+```bash+mkdir -p "$HOME/.toprank/audit-log"+```-| Priority | Action | Pages Affected | Expected Impact | Effort |-|----------|--------|---------------|-----------------|--------|-| 1 | [Specific action] | [URLs] | [Estimated click increase] | Low/Med/High |-| 2 | ... | ... | ... | ... |+Use Python to append (creates the file with a single-element array if it doesn't exist). Replace all `<FILL>` values with real data from the report before running:----+```python+import json, os+from datetime import datetime, timezone-Every recommendation must be specific and actionable. "Improve your meta-descriptions" is useless. "Update the meta description on /product-page to-include '[exact phrase from top query]' and a clear CTA — it currently has-5,400 impressions but 0.8% CTR, suggesting the snippet does not match what-searchers expect to see for this transactional query" is useful.+log_path = "$AUDIT_LOG"+existing = json.load(open(log_path)) if os.path.exists(log_path) else []++existing.append({+ "date": datetime.now(timezone.utc).strftime("%Y-%m-%d"),+ "traffic_snapshot": {+ "clicks": <FILL>,+ "impressions": <FILL>,+ "avg_ctr_pct": <FILL>,+ "avg_position": <FILL>+ },+ "top_issues": [+ # One entry per Priority Action (max 5), in priority order+ {"rank": 1, "title": "<FILL>", "type": "<FILL: title_tag|indexing|cannibalization|schema|content_gap>", "page": "<FILL>", "metric": "<FILL>", "expected_impact": "<FILL>", "status": "open"}+ ],+ "resolved_from_previous": [] # populated on next audit from Audit History comparison+})++json.dump(existing, open(log_path, "w"), indent=2)+print(f"Audit log saved to {log_path}")+```-When estimating impact, use conservative CTR curves: position 1 ~27%, position-2 ~15%, position 3 ~11%, position 4-5 ~5-8%, position 6-10 ~2-4%. Moving from-position 7 to position 3 on a 2,400 impression/month query means roughly +170-clicks/month. Use real numbers from the data.+Confirm with a one-liner: "Audit log saved to `~/.toprank/audit-log/$DOMAIN.json`."---