Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

Improve OpenClaw SEO recommendation quality

Tong Chene9f961de6cf8
diff --git a/openclaw/bin/weekly_review.py b/openclaw/bin/weekly_review.py
index cf063bd0..fafff273 100755
--- a/openclaw/bin/weekly_review.py
+++ b/openclaw/bin/weekly_review.py
@@ -5,9 +5,11 @@ from __future__ import annotations
import argparse
import json
+import math
import subprocess
import sys
import tempfile
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any
@@ -67,7 +69,107 @@ def learned_multiplier(learned: dict[str, Any], action_type: str, primary_metric
return max(0.7, min(1.5, round(raw, 3)))
-def make_issue(title: str, severity: str, confidence: float, evidence: list[str], action_type: str, target: str | None = None, base_priority: float = 0.5) -> dict[str, Any]:
+TRACKING_PARAM_NAMES = {
+ "fbclid",
+ "gclid",
+ "gbraid",
+ "wbraid",
+ "mc_cid",
+ "mc_eid",
+ "msclkid",
+}
+TRACKING_PARAM_PREFIXES = ("utm_",)
+
+
+def clamp(value: float, low: float, high: float) -> float:
+ return max(low, min(high, value))
+
+
+def expected_ctr_for_position(position: float | None) -> float:
+ """Return a conservative expected CTR percentage for a rough SERP position."""
+ if position is None or position <= 0:
+ return 1.0
+ if position <= 1.5:
+ return 18.0
+ if position <= 3:
+ return 10.0
+ if position <= 5:
+ return 6.0
+ if position <= 10:
+ return 3.0
+ if position <= 20:
+ return 1.5
+ return 0.5
+
+
+def sample_confidence(clicks: float = 0, impressions: float = 0) -> float:
+ """Soft confidence curve: larger samples earn more trust without a hard cutoff."""
+ click_component = 1 - math.exp(-max(clicks, 0) / 35)
+ impression_component = 1 - math.exp(-max(impressions, 0) / 1200)
+ return round(clamp(0.25 + (click_component * 0.45) + (impression_component * 0.3), 0.25, 1.0), 3)
+
+
+def url_context(url: str | None) -> dict[str, Any]:
+ if not url:
+ return {
+ "raw_target": None,
+ "canonical_target": None,
+ "url_quality_score": 0.8,
+ "has_tracking_params": False,
+ "operator_judgment_notes": [],
+ }
+
+ parsed = urlparse(url)
+ query_pairs = parse_qsl(parsed.query, keep_blank_values=True)
+ tracking_keys = [key for key, _ in query_pairs if key in TRACKING_PARAM_NAMES or key.startswith(TRACKING_PARAM_PREFIXES)]
+ remaining_pairs = [(key, value) for key, value in query_pairs if key not in TRACKING_PARAM_NAMES and not key.startswith(TRACKING_PARAM_PREFIXES)]
+ canonical_path = parsed.path or "/"
+ canonical_query = urlencode(remaining_pairs, doseq=True)
+ canonical = urlunparse((parsed.scheme, parsed.netloc, canonical_path, "", canonical_query, ""))
+
+ notes = []
+ if tracking_keys:
+ notes.append(f"tracking URL variant ({', '.join(sorted(set(tracking_keys)))})")
+ if query_pairs and not remaining_pairs:
+ notes.append("canonical target removes query parameters")
+
+ if tracking_keys and not remaining_pairs:
+ url_quality = 0.45
+ elif tracking_keys:
+ url_quality = 0.65
+ elif query_pairs:
+ url_quality = 0.8
+ else:
+ url_quality = 1.0
+
+ return {
+ "raw_target": url,
+ "canonical_target": canonical,
+ "url_quality_score": url_quality,
+ "has_tracking_params": bool(tracking_keys),
+ "operator_judgment_notes": notes,
+ }
+
+
+def severity_from_score(score: float) -> str:
+ if score >= 1.4:
+ return "critical"
+ if score >= 0.65:
+ return "warning"
+ return "info"
+
+
+def make_issue(
+ title: str,
+ severity: str,
+ confidence: float,
+ evidence: list[str],
+ action_type: str,
+ target: str | None = None,
+ base_priority: float = 0.5,
+ **extra: Any,
+) -> dict[str, Any]:
+ context = url_context(target)
issue = {
"title": title,
"severity": severity,
@@ -75,12 +177,235 @@ def make_issue(title: str, severity: str, confidence: float, evidence: list[str]
"evidence": evidence,
"recommended_action_type": action_type,
"base_priority": round(base_priority, 3),
+ "operator_judgment_notes": extra.pop("operator_judgment_notes", []) + context["operator_judgment_notes"],
+ "score_components": extra.pop("score_components", {}),
+ "raw_target": context["raw_target"],
+ "canonical_target": context["canonical_target"],
}
if target:
- issue["target"] = target
+ issue["target"] = context["canonical_target"] or target
+ issue.update(extra)
return issue
+
+def is_branded_query(query: str | None, brand_terms: list[str] | None) -> bool:
+ if not query or not brand_terms:
+ return False
+ q = query.lower()
+ return any(term and term.lower() in q for term in brand_terms)
+
+
+def goal_alignment_for_query(query: str | None, brand_terms: list[str] | None) -> tuple[float, list[str]]:
+ if is_branded_query(query, brand_terms):
+ return 0.35, ["branded/navigational query; lower priority for non-brand growth"]
+ return 1.0, []
+
+
+def decline_issue(page: dict[str, Any]) -> dict[str, Any]:
+ raw_target = page.get("page")
+ context = url_context(raw_target)
+ clicks_now = float(page.get("clicks_now") or 0)
+ clicks_prev = float(page.get("clicks_prev") or 0)
+ lost_clicks = max(clicks_prev - clicks_now, 0.0)
+ change_pct = float(page.get("change_pct") or 0)
+ confidence = sample_confidence(clicks=clicks_prev + clicks_now)
+ impact_score = clamp(lost_clicks / 50, 0.05, 2.0)
+ actionability_score = 0.75
+ action_type = "page_improvement"
+ title_target = raw_target
+ notes = []
+ if context["has_tracking_params"]:
+ action_type = "canonical_or_tracking_investigation"
+ actionability_score = 0.45
+ notes.append("treat as attribution/canonical investigation before editing page content")
+ title_target = context["canonical_target"] or raw_target
+ if lost_clicks < 25:
+ notes.append("low absolute click loss; percentage drop may overstate impact")
+
+ url_quality = float(context["url_quality_score"])
+ score = impact_score * confidence * actionability_score * url_quality
+ return make_issue(
+ f"Traffic dropped on {title_target}",
+ severity_from_score(score),
+ confidence,
+ [
+ f"Clicks changed {change_pct}% vs prior period.",
+ f"Current clicks: {clicks_now:g} | previous clicks: {clicks_prev:g} | lost clicks: {lost_clicks:g}",
+ ],
+ action_type,
+ target=raw_target,
+ base_priority=impact_score,
+ expected_click_delta=round(-lost_clicks, 1),
+ priority_score=round(score, 3),
+ score_components={
+ "expected_impact": round(impact_score, 3),
+ "confidence_score": confidence,
+ "goal_alignment_score": 1.0,
+ "actionability_score": actionability_score,
+ "url_quality_score": url_quality,
+ },
+ operator_judgment_notes=notes,
+ )
+
+
+def ctr_gap_issue(gap: dict[str, Any], brand_terms: list[str] | None = None) -> dict[str, Any]:
+ raw_target = gap.get("page")
+ clicks = float(gap.get("clicks") or 0)
+ impressions = float(gap.get("impressions") or 0)
+ ctr = float(gap.get("ctr") or 0)
+ position = float(gap.get("position") or 0)
+ expected_ctr = expected_ctr_for_position(position)
+ incremental_clicks = max(impressions * ((expected_ctr - ctr) / 100), 0.0)
+ impact_score = clamp(incremental_clicks / 50, 0.05, 2.0)
+ confidence = sample_confidence(clicks=clicks, impressions=impressions)
+ actionability_score = 0.95
+ url_quality = float(url_context(raw_target)["url_quality_score"])
+ query = gap.get("query")
+ goal_alignment_score, goal_notes = goal_alignment_for_query(query, brand_terms)
+ score = impact_score * confidence * goal_alignment_score * actionability_score * url_quality
+ evidence = [
+ f"{impressions:g} impressions with CTR {ctr}%.",
+ f"Average position {position:g}; conservative expected CTR {expected_ctr}% suggests ~{incremental_clicks:.0f} incremental-click upside.",
+ ]
+ if query:
+ evidence.append(f"Underperforming query: {query}")
+ return make_issue(
+ f"High-impression page with low CTR: {raw_target}",
+ severity_from_score(score),
+ confidence,
+ evidence,
+ "meta_tags",
+ target=raw_target,
+ base_priority=impact_score,
+ expected_click_delta=round(incremental_clicks, 1),
+ priority_score=round(score, 3),
+ score_components={
+ "expected_impact": round(impact_score, 3),
+ "confidence_score": confidence,
+ "goal_alignment_score": goal_alignment_score,
+ "actionability_score": actionability_score,
+ "url_quality_score": url_quality,
+ },
+ operator_judgment_notes=["clear snippet/title lever with measurable upside", *goal_notes],
+ )
+
+
+def cannibalization_issue(cannibal: dict[str, Any], brand_terms: list[str] | None = None) -> dict[str, Any]:
+ raw_target = cannibal.get("winner_page")
+ impressions = float(cannibal.get("total_impressions") or 0)
+ clicks = float(cannibal.get("total_clicks") or 0)
+ impact_score = clamp(impressions / 5000, 0.05, 1.4)
+ confidence = sample_confidence(clicks=clicks, impressions=impressions)
+ actionability_score = 0.65
+ url_quality = float(url_context(raw_target)["url_quality_score"])
+ goal_alignment_score, goal_notes = goal_alignment_for_query(cannibal.get("query"), brand_terms)
+ score = impact_score * confidence * goal_alignment_score * actionability_score * url_quality
+ loser_pages = cannibal.get("loser_pages", [])
+ return make_issue(
+ f"Cannibalization on query '{cannibal.get('query')}'",
+ severity_from_score(score),
+ confidence,
+ [
+ f"Winner page: {raw_target}",
+ f"Competing pages: {', '.join(loser_pages[:8])}{'...' if len(loser_pages) > 8 else ''}",
+ f"Affected query set: {impressions:g} impressions and {clicks:g} clicks.",
+ ],
+ "internal_links",
+ target=raw_target,
+ base_priority=impact_score,
+ expected_click_delta=None,
+ priority_score=round(score, 3),
+ score_components={
+ "expected_impact": round(impact_score, 3),
+ "confidence_score": confidence,
+ "goal_alignment_score": goal_alignment_score,
+ "actionability_score": actionability_score,
+ "url_quality_score": url_quality,
+ },
+ operator_judgment_notes=["needs intent review before redirects/canonicals", *goal_notes],
+ )
+
+
+def query_ctr_issue(opp: dict[str, Any], brand_terms: list[str] | None = None) -> dict[str, Any]:
+ impressions = float(opp.get("impressions") or 0)
+ clicks = float(opp.get("clicks") or 0)
+ ctr = float(opp.get("ctr") or 0)
+ position = float(opp.get("position") or 0)
+ expected_ctr = expected_ctr_for_position(position)
+ incremental_clicks = max(impressions * ((expected_ctr - ctr) / 100), 0.0)
+ impact_score = clamp(incremental_clicks / 65, 0.05, 1.3)
+ confidence = sample_confidence(clicks=clicks, impressions=impressions)
+ actionability_score = 0.55 # Query-only; needs page mapping before editing.
+ goal_alignment_score, goal_notes = goal_alignment_for_query(opp.get("query"), brand_terms)
+ score = impact_score * confidence * goal_alignment_score * actionability_score
+ return make_issue(
+ f"Query-level CTR opportunity: {opp.get('query')}",
+ severity_from_score(score),
+ confidence,
+ [
+ f"{impressions:g} impressions with CTR {ctr}%.",
+ f"Average position {position:g}; conservative expected CTR {expected_ctr}% suggests ~{incremental_clicks:.0f} incremental-click upside.",
+ ],
+ "meta_tags",
+ base_priority=impact_score,
+ expected_click_delta=round(incremental_clicks, 1),
+ priority_score=round(score, 3),
+ score_components={
+ "expected_impact": round(impact_score, 3),
+ "confidence_score": confidence,
+ "goal_alignment_score": goal_alignment_score,
+ "actionability_score": actionability_score,
+ "url_quality_score": 1.0,
+ },
+ operator_judgment_notes=["query-level signal; map to a page before editing", *goal_notes],
+ )
+
+
+def declining_query_issue(query: dict[str, Any], brand_terms: list[str] | None = None) -> dict[str, Any]:
+ clicks_now = float(query.get("clicks_now") or 0)
+ clicks_prev = float(query.get("clicks_prev") or 0)
+ lost_clicks = max(clicks_prev - clicks_now, 0.0)
+ confidence = sample_confidence(clicks=clicks_prev + clicks_now)
+ impact_score = clamp(lost_clicks / 50, 0.05, 1.0)
+ actionability_score = 0.5
+ goal_alignment_score, goal_notes = goal_alignment_for_query(query.get("query"), brand_terms)
+ score = impact_score * confidence * goal_alignment_score * actionability_score
+ return make_issue(
+ f"Query demand fell for '{query.get('query')}'",
+ severity_from_score(score),
+ confidence,
+ [
+ f"Clicks changed {query.get('change_pct')}% vs prior period.",
+ f"Current clicks: {clicks_now:g} | previous clicks: {clicks_prev:g} | lost clicks: {lost_clicks:g}",
+ ],
+ "content_refresh",
+ base_priority=impact_score,
+ expected_click_delta=round(-lost_clicks, 1),
+ priority_score=round(score, 3),
+ score_components={
+ "expected_impact": round(impact_score, 3),
+ "confidence_score": confidence,
+ "goal_alignment_score": goal_alignment_score,
+ "actionability_score": actionability_score,
+ "url_quality_score": 1.0,
+ },
+ operator_judgment_notes=["query-level regression; needs SERP/page diagnosis before editing", *goal_notes],
+ )
+
+
+def dedupe_candidates(candidates: list[dict[str, Any]]) -> list[dict[str, Any]]:
+ by_key: dict[str, dict[str, Any]] = {}
+ for candidate in candidates:
+ key = candidate.get("canonical_target") or candidate.get("title")
+ existing = by_key.get(key)
+ if not existing or candidate.get("priority_score", 0) > existing.get("priority_score", 0):
+ by_key[key] = candidate
+ elif existing:
+ existing.setdefault("operator_judgment_notes", []).append(f"Also saw signal: {candidate['title']}")
+ return list(by_key.values())
+
+
def derive_candidate_issues(data: dict[str, Any]) -> list[dict[str, Any]]:
issues: list[dict[str, Any]] = []
comparison = data.get("comparison") or {}
@@ -89,107 +414,30 @@ def derive_candidate_issues(data: dict[str, Any]) -> list[dict[str, Any]]:
ctr_opps = data.get("ctr_opportunities") or []
declining_pages = comparison.get("declining_pages") or []
declining_queries = comparison.get("declining_queries") or []
+ brand_terms = data.get("_brand_terms") or []
- if declining_pages:
- page = declining_pages[0]
- issues.append(
- make_issue(
- f"Traffic dropped on {page.get('page')}",
- "critical",
- 0.84,
- [
- f"Clicks changed {page.get('change_pct')}% vs prior period.",
- f"Current clicks: {page.get('clicks_now')} | previous clicks: {page.get('clicks_prev')}",
- ],
- "page_improvement",
- target=page.get("page"),
- base_priority=0.95,
- )
- )
-
- if ctr_gaps:
- gap = ctr_gaps[0]
- issues.append(
- make_issue(
- f"High-impression page with low CTR: {gap.get('page')}",
- "warning",
- 0.78,
- [
- f"{gap.get('impressions')} impressions with CTR {gap.get('ctr')}%.",
- f"Average position {gap.get('position')} suggests snippet improvements may help.",
- ],
- "meta_tags",
- target=gap.get("page"),
- base_priority=0.8,
- )
- )
-
- if cannibalization:
- cannibal = cannibalization[0]
- issues.append(
- make_issue(
- f"Cannibalization on query '{cannibal.get('query')}'",
- "warning",
- 0.73,
- [
- f"Winner page: {cannibal.get('winner_page')}",
- f"Competing pages: {', '.join(cannibal.get('loser_pages', []))}",
- ],
- "internal_links",
- target=cannibal.get("winner_page"),
- base_priority=0.72,
- )
- )
-
- if ctr_opps:
- opp = ctr_opps[0]
- issues.append(
- make_issue(
- f"Query-level CTR opportunity: {opp.get('query')}",
- "info",
- 0.68,
- [
- f"{opp.get('impressions')} impressions with CTR {opp.get('ctr')}%.",
- f"Average position {opp.get('position')}.",
- ],
- "meta_tags",
- base_priority=0.64,
- )
- )
+ issues.extend(decline_issue(page) for page in declining_pages[:8])
+ issues.extend(ctr_gap_issue(gap, brand_terms) for gap in ctr_gaps[:8])
+ issues.extend(cannibalization_issue(cannibal, brand_terms) for cannibal in cannibalization[:5])
+ issues.extend(query_ctr_issue(opp, brand_terms) for opp in ctr_opps[:5])
+ issues.extend(declining_query_issue(query, brand_terms) for query in declining_queries[:5])
- if declining_queries:
- query = declining_queries[0]
- issues.append(
- make_issue(
- f"Query demand fell for '{query.get('query')}'",
- "warning",
- 0.66,
- [
- f"Clicks changed {query.get('change_pct')}% vs prior period.",
- f"Current clicks: {query.get('clicks_now')} | previous clicks: {query.get('clicks_prev')}",
- ],
- "content_refresh",
- base_priority=0.62,
- )
- )
-
- return issues
+ return dedupe_candidates(issues)
def apply_prioritization(candidates: list[dict[str, Any]], learned: dict[str, Any], primary_metric: str) -> list[dict[str, Any]]:
- severity_weight = {"critical": 1.0, "warning": 0.75, "info": 0.45}
ranked = []
for item in candidates:
multiplier = learned_multiplier(learned, item["recommended_action_type"], primary_metric)
- score = item.get("base_priority", 0.5) * severity_weight.get(item.get("severity", "warning"), 0.6) * multiplier * (0.6 + item.get("confidence", 0.5))
+ score = float(item.get("priority_score", item.get("base_priority", 0.5))) * multiplier
enriched = dict(item)
enriched["priority_score"] = round(score, 3)
enriched["learned_multiplier"] = multiplier
+ enriched["severity"] = severity_from_score(score)
ranked.append(enriched)
ranked.sort(key=lambda issue: issue["priority_score"], reverse=True)
return ranked
-
def build_payload(site_id: str, analysis: dict[str, Any], learned: dict[str, Any], goal: dict[str, Any] | None) -> dict[str, Any]:
metrics = metric_snapshot_from_analysis(analysis)
primary_metric = None
@@ -226,35 +474,51 @@ def build_payload(site_id: str, analysis: dict[str, Any], learned: dict[str, Any
for idx, issue in enumerate(top_issues, start=1):
action_id = f"weekly_action_{idx:02d}"
action_type = issue["recommended_action_type"]
+ expected_delta = issue.get("expected_click_delta")
+ expected_impact = f"Address {action_type.replace('_', ' ')} opportunity surfaced in the weekly review."
+ if isinstance(expected_delta, (int, float)) and expected_delta > 0:
+ expected_impact = f"Estimated upside: ~{expected_delta:g} incremental clicks if the opportunity is fixed."
+ elif isinstance(expected_delta, (int, float)) and expected_delta < 0:
+ expected_impact = f"Regression signal: ~{abs(expected_delta):g} lost clicks vs prior period; investigate before changing content."
action_entries.append(
{
"action_id": action_id,
"title": issue["title"],
"type": action_type,
"priority_score": issue["priority_score"],
- "expected_impact": f"Address {action_type.replace('_', ' ')} opportunity surfaced in the weekly review.",
+ "expected_impact": expected_impact,
"requires_approval": action_type not in {"manual_review"},
"reversibility": "high",
"owner": "operator",
"target": issue.get("target"),
+ "raw_target": issue.get("raw_target"),
+ "canonical_target": issue.get("canonical_target"),
+ "score_components": issue.get("score_components", {}),
+ "operator_judgment_notes": issue.get("operator_judgment_notes", []),
"learned_multiplier": issue.get("learned_multiplier", 1.0),
}
)
if idx == 1 and action_type != "manual_review":
queue_items.append(
{
- "item_id": f"followup_{site_id}_{action_type}_{analysis['period']['days']}d",
- "type": "feedback_check",
- "status": "pending",
- "due_at": future_iso(14),
- "notes": f"Review the impact of the weekly action: {issue['title']}",
+ "item_id": f"proposal_{site_id}_{action_type}_{analysis['period']['days']}d",
+ "type": "action_proposal",
+ "status": "pending_approval",
+ "notes": f"Approve, reject, or revise the weekly action: {issue['title']}",
+ "action_id": action_id,
"action_type": action_type,
"target": issue.get("target"),
+ "raw_target": issue.get("raw_target"),
+ "canonical_target": issue.get("canonical_target"),
"primary_metric": primary_metric,
"primary_direction": "higher_better" if "position" not in primary_metric else "lower_better",
"success_threshold_pct": 0.1,
"baseline_metrics": metrics,
"guardrail_metrics": [],
+ "follow_up_after_approval_days": 14,
+ "approval_required": True,
+ "score_components": issue.get("score_components", {}),
+ "operator_judgment_notes": issue.get("operator_judgment_notes", []),
}
)
@@ -293,6 +557,11 @@ def build_payload(site_id: str, analysis: dict[str, Any], learned: dict[str, Any
"checks": [
{"name": "gsc analysis available", "status": "pass", "notes": "Weekly review generated from Search Console data."},
{"name": "action plan generated", "status": "pass", "notes": f"Primary metric for follow-up scoring: {primary_metric}."},
+ {
+ "name": "recommendation quality gate",
+ "status": "pass" if top_issues[0].get("priority_score", 0) >= 0.35 else "warning",
+ "notes": "; ".join(top_issues[0].get("operator_judgment_notes", [])) or "Top action has explicit score components for operator review.",
+ },
],
"follow_up_due": None,
},
@@ -336,6 +605,7 @@ def main(argv: list[str]) -> int:
brand_terms = args.brand_terms if args.brand_terms is not None else ",".join(profile.get("brand_terms", []))
analysis = run_analysis(site_property, args.days, brand_terms)
+ analysis["_brand_terms"] = profile.get("brand_terms", [])
payload = build_payload(site_id, analysis, learned, active_goal)
result = persist_payload(args.site, payload, root=root)
result["primary_metric"] = payload["queue_items"][0]["primary_metric"] if payload.get("queue_items") else None
diff --git a/openclaw/shared/recommendation-quality.md b/openclaw/shared/recommendation-quality.md
new file mode 100644
index 00000000..469e0efc
--- /dev/null
+++ b/openclaw/shared/recommendation-quality.md
@@ -0,0 +1,40 @@
+# Recommendation Quality
+
+The OpenClaw SEO operator should behave like an analyst, not an alert router.
+
+## Principle
+
+Prefer recommendations with clear expected upside, enough evidence, and an obvious next lever. Avoid ranking noisy metric movement above actionable opportunities just because the percentage change is large.
+
+## Judgment levers
+
+Each recommendation should expose the inputs that drove ranking:
+
+- `expected_impact` — estimated click upside or click loss, using absolute impact when possible
+- `confidence_score` — sample size and signal stability
+- `goal_alignment_score` — whether the signal supports the active goal, especially non-brand growth
+- `actionability_score` — whether there is a clear SEO lever vs a vague investigation
+- `url_quality_score` — whether the URL is canonical/actionable or a tracking/parameter variant
+- `learned_multiplier` — site-local prior from previous outcomes
+
+These are not hard approval rules. They are decision levers for the operator and the human reviewer.
+
+## Common false positives
+
+- Tiny-denominator drops, e.g. 13 clicks to 3 clicks, especially when ranked by percent change
+- Tracking URLs and UTM variants treated as standalone strategic pages
+- Branded/navigational query noise outranking non-brand growth opportunities
+- Cannibalization reports where the “winner” is not actually the intended page
+- Query-level opportunities that have not been mapped to a concrete page
+
+## Preferred behavior
+
+- Preserve the raw signal in evidence.
+- Canonicalize the action target when the raw URL is a tracking variant.
+- Reclassify tracking-param traffic drops as investigation work instead of content/page edits.
+- Let high-impression, high-position, low-CTR opportunities outrank low-volume noisy regressions.
+- Explain why the top action is actionable and what would make it unsafe or low-confidence.
+
+## Approval boundary
+
+A high score means “worth proposing,” not “safe to publish.” Repo edits, CMS writes, PRs, redirects, canonical changes, and production metadata changes still require explicit approval.
diff --git a/openclaw/skills/toprank-weekly-review/SKILL.md b/openclaw/skills/toprank-weekly-review/SKILL.md
index 60ea2e9a..95339222 100644
--- a/openclaw/skills/toprank-weekly-review/SKILL.md
+++ b/openclaw/skills/toprank-weekly-review/SKILL.md
@@ -9,15 +9,16 @@ metadata: { "openclaw": { "emoji": "📈", "homepage": "https://github.com/nowor
1. Read `{baseDir}/../../shared/adapter-rules.md`.
2. Read `{baseDir}/../../shared/artifact-contract.md`.
3. Read `{baseDir}/../../shared/policy.md`.
-4. Resolve the target `site_id`; if no site was specified and multiple sites are active, run portfolio review first or ask the user which site to review.
-5. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-analysis/SKILL.md`.
-6. Prefer the automated runner:
+4. Read `{baseDir}/../../shared/recommendation-quality.md`.
+5. Resolve the target `site_id`; if no site was specified and multiple sites are active, run portfolio review first or ask the user which site to review.
+6. Read and follow the canonical Toprank skill at `{baseDir}/../../../seo/seo-analysis/SKILL.md`.
+7. Prefer the automated runner:
- `python3 {baseDir}/../../bin/weekly_review.py <site_id-or-url>`
- add `--gsc-property` if the site profile does not already contain one
- add `--analysis-file` when testing against a saved GSC analysis JSON fixture
-7. The runner will generate and persist the review artifacts automatically.
-8. Verify that the run wrote `audit.json`, `action-plan.json`, and `verification.json`, refreshed `latest-state.json`, and created a follow-up queue item.
-9. If the next action requires editing a site repo, CMS, publishing content, or opening a PR, stop and ask for approval before doing it.
+8. The runner will generate and persist the review artifacts automatically.
+9. Verify that the run wrote `audit.json`, `action-plan.json`, and `verification.json`, refreshed `latest-state.json`, and created a follow-up queue item.
+10. If the next action requires editing a site repo, CMS, publishing content, or opening a PR, stop and ask for approval before doing it.
## Wrapper job
diff --git a/openclaw/tests/test_weekly_review_scoring.py b/openclaw/tests/test_weekly_review_scoring.py
new file mode 100644
index 00000000..c35f5c3c
--- /dev/null
+++ b/openclaw/tests/test_weekly_review_scoring.py
@@ -0,0 +1,103 @@
+import sys
+import unittest
+from pathlib import Path
+
+BIN_DIR = Path(__file__).resolve().parents[1] / "bin"
+if str(BIN_DIR) not in sys.path:
+ sys.path.insert(0, str(BIN_DIR))
+
+import weekly_review
+
+
+class WeeklyReviewScoringTest(unittest.TestCase):
+ def base_analysis(self) -> dict:
+ return {
+ "site": "sc-domain:example.com",
+ "period": {"start": "2026-04-01", "end": "2026-04-28", "days": 28},
+ "summary": {"clicks": 2000, "impressions": 200000, "ctr": 1.0, "position": 8.0},
+ "branded_split": {
+ "branded": {"clicks": 800, "impressions": 10000},
+ "non_branded": {"clicks": 350, "impressions": 20000},
+ },
+ "comparison": {"declining_pages": [], "declining_queries": []},
+ "ctr_gaps_by_page": [],
+ "ctr_opportunities": [],
+ "cannibalization": [],
+ }
+
+ def test_high_impression_ctr_gap_beats_low_volume_utm_drop(self) -> None:
+ analysis = self.base_analysis()
+ analysis["comparison"]["declining_pages"] = [
+ {
+ "page": "https://www.example.com/?utm_source=google_map",
+ "clicks_now": 3,
+ "clicks_prev": 13,
+ "change_pct": -76.9,
+ }
+ ]
+ analysis["ctr_gaps_by_page"] = [
+ {
+ "query": "dog boarding cost",
+ "page": "https://www.example.com/blog/dog-boarding-cost",
+ "clicks": 2,
+ "impressions": 1681,
+ "ctr": 0.12,
+ "position": 2.8,
+ }
+ ]
+
+ payload = weekly_review.build_payload("example.com", analysis, {"priors": {}}, None)
+ top_action = payload["action_plan"]["actions"][0]
+ issues = payload["audit"]["issues"]
+
+ self.assertEqual(top_action["type"], "meta_tags")
+ self.assertEqual(top_action["target"], "https://www.example.com/blog/dog-boarding-cost")
+ self.assertGreater(issues[0]["priority_score"], issues[1]["priority_score"])
+ self.assertIn("score_components", issues[0])
+ self.assertEqual(payload["queue_items"][0]["type"], "action_proposal")
+ self.assertEqual(payload["queue_items"][0]["status"], "pending_approval")
+ self.assertNotIn("due_at", payload["queue_items"][0])
+
+ def test_tracking_url_decline_keeps_raw_target_but_canonicalizes_action_target(self) -> None:
+ issue = weekly_review.decline_issue(
+ {
+ "page": "https://www.example.com/?utm_source=google_map&utm_medium=business_profile",
+ "clicks_now": 3,
+ "clicks_prev": 13,
+ "change_pct": -76.9,
+ }
+ )
+
+ self.assertEqual(issue["recommended_action_type"], "canonical_or_tracking_investigation")
+ self.assertEqual(issue["raw_target"], "https://www.example.com/?utm_source=google_map&utm_medium=business_profile")
+ self.assertEqual(issue["target"], "https://www.example.com/")
+ self.assertLess(issue["score_components"]["url_quality_score"], 1.0)
+ self.assertTrue(any("tracking" in note for note in issue["operator_judgment_notes"]))
+
+ def test_absolute_loss_decline_beats_tiny_percent_drop(self) -> None:
+ analysis = self.base_analysis()
+ analysis["comparison"]["declining_pages"] = [
+ {
+ "page": "https://www.example.com/?utm_source=google_map",
+ "clicks_now": 3,
+ "clicks_prev": 13,
+ "change_pct": -76.9,
+ },
+ {
+ "page": "https://www.example.com/blog/dog-sitting-costs",
+ "clicks_now": 58,
+ "clicks_prev": 103,
+ "change_pct": -43.7,
+ },
+ ]
+
+ payload = weekly_review.build_payload("example.com", analysis, {"priors": {}}, None)
+ top_action = payload["action_plan"]["actions"][0]
+
+ self.assertEqual(top_action["target"], "https://www.example.com/blog/dog-sitting-costs")
+ self.assertEqual(top_action["type"], "page_improvement")
+ self.assertIn("45", top_action["expected_impact"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/seo/seo-analysis/scripts/analyze_gsc.py b/seo/seo-analysis/scripts/analyze_gsc.py
index c62bf4cc..f9a00c0a 100644
--- a/seo/seo-analysis/scripts/analyze_gsc.py
+++ b/seo/seo-analysis/scripts/analyze_gsc.py
@@ -213,9 +213,18 @@ def pull_period_comparison(token, site, days):
"page": page,
"clicks_now": curr["clicks"],
"clicks_prev": prev["clicks"],
- "change_pct": pct
+ "click_delta": delta,
+ "absolute_click_loss": abs(delta),
+ "change_pct": pct,
+ "impressions_now": curr.get("impressions", 0),
+ "impressions_prev": prev.get("impressions", 0),
+ "impression_delta": curr.get("impressions", 0) - prev.get("impressions", 0),
+ "ctr_now": round(curr.get("ctr", 0) * 100, 2),
+ "ctr_prev": round(prev.get("ctr", 0) * 100, 2),
+ "position_now": round(curr.get("position", 0), 1),
+ "position_prev": round(prev.get("position", 0), 1),
})
- page_changes.sort(key=lambda x: x["change_pct"])
+ page_changes.sort(key=lambda x: (-x.get("absolute_click_loss", 0), x["change_pct"]))
# Queries comparison
curr_q = fetch(start_curr, end_curr, "query")
@@ -232,9 +241,18 @@ def pull_period_comparison(token, site, days):
"query": q,
"clicks_now": curr["clicks"],
"clicks_prev": prev["clicks"],
- "change_pct": pct
+ "click_delta": delta,
+ "absolute_click_loss": abs(delta),
+ "change_pct": pct,
+ "impressions_now": curr.get("impressions", 0),
+ "impressions_prev": prev.get("impressions", 0),
+ "impression_delta": curr.get("impressions", 0) - prev.get("impressions", 0),
+ "ctr_now": round(curr.get("ctr", 0) * 100, 2),
+ "ctr_prev": round(prev.get("ctr", 0) * 100, 2),
+ "position_now": round(curr.get("position", 0), 1),
+ "position_prev": round(prev.get("position", 0), 1),
})
- query_changes.sort(key=lambda x: x["change_pct"])
+ query_changes.sort(key=lambda x: (-x.get("absolute_click_loss", 0), x["change_pct"]))
return {
"period": f"{start_curr.isoformat()} to {end_curr.isoformat()}",
diff --git a/test/unit/test_analyze_gsc.py b/test/unit/test_analyze_gsc.py
index 7b60bacb..4be063cc 100644
--- a/test/unit/test_analyze_gsc.py
+++ b/test/unit/test_analyze_gsc.py
@@ -322,16 +322,34 @@ class TestPeriodComparison(unittest.TestCase):
)
self.assertLess(result['declining_pages'][0]['change_pct'], 0)
- def test_result_sorted_by_change_pct_ascending(self):
+ def test_result_sorted_by_absolute_click_loss_first(self):
result = self._run_comparison(
- curr_pages={'/a': 20, '/b': 10},
- prev_pages={'/a': 100, '/b': 100}, # /b drops more
+ curr_pages={'/tiny-percent-drop': 3, '/bigger-loss': 58},
+ prev_pages={'/tiny-percent-drop': 13, '/bigger-loss': 103},
curr_queries={},
prev_queries={},
)
pages = result['declining_pages']
- if len(pages) >= 2:
- self.assertLessEqual(pages[0]['change_pct'], pages[1]['change_pct'])
+ self.assertEqual(pages[0]['page'], '/bigger-loss')
+ self.assertEqual(pages[0]['absolute_click_loss'], 45)
+ self.assertEqual(pages[1]['absolute_click_loss'], 10)
+
+ def test_period_comparison_includes_richer_metadata(self):
+ result = self._run_comparison(
+ curr_pages={'/page': 40},
+ prev_pages={'/page': 100},
+ curr_queries={'keyword': 30},
+ prev_queries={'keyword': 60},
+ )
+ page = result['declining_pages'][0]
+ self.assertEqual(page['click_delta'], -60)
+ self.assertEqual(page['absolute_click_loss'], 60)
+ self.assertIn('impressions_now', page)
+ self.assertIn('ctr_now', page)
+ self.assertIn('position_now', page)
+ query = result['declining_queries'][0]
+ self.assertEqual(query['click_delta'], -30)
+ self.assertEqual(query['absolute_click_loss'], 30)
class TestGscQueryErrorHandling(unittest.TestCase):