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.pyindex cf063bd0..fafff273 100755--- a/openclaw/bin/weekly_review.py+++ b/openclaw/bin/weekly_review.py@@ -5,9 +5,11 @@ from __future__ import annotationsimport argparseimport json+import mathimport subprocessimport sysimport tempfile+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparsefrom datetime import datetime, timedelta, timezonefrom pathlib import Pathfrom typing import Any@@ -67,7 +69,107 @@ def learned_multiplier(learned: dict[str, Any], action_type: str, primary_metricreturn 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))) * multiplierenriched = 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, Anyfor 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 Nonediff --git a/openclaw/shared/recommendation-quality.md b/openclaw/shared/recommendation-quality.mdnew file mode 100644index 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.mdindex 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/nowor1. 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 jobdiff --git a/openclaw/tests/test_weekly_review_scoring.py b/openclaw/tests/test_weekly_review_scoring.pynew file mode 100644index 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.pyindex 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 comparisoncurr_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.pyindex 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):