description: "Specialized: AI Share of Voice (SoV) & Citability Monitoring Loop" version: "1.0"

/seo-monitor-geo

Purpose

Dedicated workflow to measure and track a brand's Share of Voice (SoV) and citation presence (Citability) across AI search engines. It executes the Live Query Loop, runs model evaluations, and compiles the SoV report.

This workflow is called by /seo-monitor or can be run independently to check AI visibility.

Skills Activated (2)

Prerequisites

• Required: Project configuration project.json must exist.
• Required: Prompt database .seo/data/brand-prompts.toon must be initialized via /seo-research-brand-prompts.

Sub-Agent Coordination

• Primary Executor: @[rd/algo-forecaster] (Leads AI search evaluations and SOV compilation)
• Sub-Agents: @[rd/seo-bi-analyst] (Saves evaluation metrics and formats outputs)

Anti-Simulation & Grounding Protocol

Rate Limit & Connection Error Fallback

Khi thực hiện quét số lượng lớn câu hỏi, nếu gặp lỗi giới hạn tần suất (Rate Limit 429) hoặc lỗi kết nối mạng khiến không thể gọi công cụ tìm kiếm:

1. Tuyệt đối không bịa dữ liệu: Không được phép tự ý giả lập hoặc suy đoán kết quả cho các câu hỏi bị lỗi.
2. Ghi nhận lỗi có cấu trúc: Ghi nhận rõ trạng thái lỗi vào tệp kết quả tạm thời:
   • brand_mentioned: false
   • sentiment: "neutral"
   • evidence_snippet: "ERROR: [Chi tiết lỗi kết nối hoặc mã lỗi 429]"
   • url_cited: ""
3. Tính toán minh bạch: Báo cáo tổng hợp cuối cùng vẫn tiến hành biên dịch với các câu hỏi thành công, nhưng phải hiển thị rõ tỉ lệ lỗi kết nối hoặc lỗi Rate Limit (ví dụ: Tỉ lệ quét lỗi: 10%) để người dùng nắm bắt được tính toàn vẹn của dữ liệu và đưa ra quyết định quét lại nếu cần.

Steps

1. Init context & Load prompts (Primary Agent: @[rd/algo-forecaster]):

   • Compute PROJECT_DIR = .seo
   • Check if {PROJECT_DIR}/data/brand-prompts.toon exists. If not ➔ báo lỗi: "Vui lòng chạy /seo-research-brand-prompts để khởi tạo câu hỏi theo dõi trước."

2. Execute Live Query Loop (Funnel Evaluation) (Primary Agent: @[rd/algo-forecaster]):

   • Chia danh sách truy vấn thành các lô (batch) tối đa 3 câu hỏi để tránh Rate Limit.
   • Gọi song song tối đa 3 sub-agent (self hoặc rd/algo-forecaster) để chạy native tool search_web cho từng câu hỏi, trích xuất đoạn văn bản AI Overviews.
   • Sub-agents sử dụng decoupled prompt brand_sov_evaluation.md để tự đánh giá thực thể thương hiệu, sentiment, và trích xuất url nguồn trích dẫn dạng TOON.
   • Áp dụng chặt chẽ Rate Limit & Connection Error Fallback nếu xảy ra sự cố trong quá trình gọi tìm kiếm.
   • Gom dữ liệu TOON kết quả của các sub-agents và lưu vào file tạm .seo/data/temp-evals.toon.

3. Compile SoV Report (Primary Agent: @[rd/algo-forecaster]):

   • Biên dịch kết quả bằng script Python:

     python .agents/scripts/run_plugin_script.py seo-geo-monitor brand_sov_compiler.py <domain> --evals-file .seo/data/temp-evals.toon --prompts-file .seo/data/brand-prompts.toon
     

   • Xóa file tạm .seo/data/temp-evals.toon sau khi hoàn tất.

4. Output Summary (Primary Agent: @[rd/seo-bi-analyst]):

   • Báo cáo kết quả: Ghi nhận điểm số AI SoV và dẫn đường dẫn file báo cáo .seo/reports/brand-sov-{date}.md ra màn hình.