description: "Research phase orchestrator: Adaptive Semantic Clustering (Human-in-the-loop)" version: "1.0"

/seo-research-clustering

Purpose

Executes the pure Machine Learning portion of Vector Clustering. Converts the cleaned keywords.json into semantic clusters (clusters.json) using Python scripts (Agglomerative Clustering / Entity-Guided Word Jaccard fallback).

Quy trình này cung cấp một Hard Pause Gate để con người (Human-in-the-loop) duyệt, tinh chỉnh, gộp hoặc tách các cụm từ khóa bằng tay trước khi giao cho LLM đánh giá ý định ở bước tiếp theo, nhằm tiết kiệm token và đảm bảo độ chính xác.

Skills Activated (up to 10)

Prerequisites

• Yêu cầu cấu hình dự án project.json đã có sẵn.
• Yêu cầu keywords.json đã hoàn thành và phê duyệt (từ /seo-research-keywords).

Sub-Agent Coordination

• Primary Executor: @[topical-authority-planner] (groups semantic keywords and merges intent clusters)
• Co-owner: @[seo-bi-analyst] (audits cluster metrics and search console CTR mapping)

Execution Flow

Step 1: Adaptive Semantic Clustering

• Chạy script Python vector_clustering.py để phân cụm từ khóa thích ứng dựa trên tập keywords.json.
• Lệnh: python .agents/skills/seo-plan/scripts/vector_clustering.py {domain}
• Output chính: .seo/data/clusters.json.

🛑 Hard Pause Gate 1d: Human-in-the-loop Review

• Hiển thị thông báo trên màn hình: "Thuật toán đã gom thành X cụm. Vui lòng mở file clusters.json để kiểm tra. Bạn có thể tự do di chuyển từ khóa, gộp cụm hoặc tách cụm thủ công theo ý đồ kinh doanh."
• Cập nhật project.json.workflow_checkpoint với {workflow: "seo-research-clustering", status: "completed"}.
• Chờ người dùng xác nhận Y hoặc báo đã duyệt xong trước khi cho phép chạy /seo-research-topical-map.

Final Dashboard

Trình bày báo cáo tổng kết (Final Dashboard) bằng Markdown trực quan, hướng người dùng (user-facing) và cung cấp thông tin chi tiết về tập dữ liệu vừa tạo. Tránh dùng hộp ASCII khô khan. Sử dụng template sau:

# 🎯 Báo cáo Semantic Clustering — `{domain}`

**Trạng thái**: Hoàn tất gom cụm từ khóa (Phase 3/5)

## 📊 Tổng quan Cụm (Clusters)

Thuật toán Vector Clustering đã xử lý và nhóm thành công các từ khóa thành **{count}** cụm ngữ nghĩa:

- **Số lượng cụm tạo thành**: {count} cụm
- *(Trích xuất nhanh 3-5 cụm tiêu biểu ở đây để người dùng dễ hình dung. VD: Cụm "Dịch vụ SEO", Cụm "Báo giá SEO"...)*

## ⚠️ Hành Động Bắt Buộc (ACTION REQUIRED)

Hệ thống đã gom cụm tự động bằng Machine Learning. Tuy nhiên, để đảm bảo tính chính xác tuyệt đối theo góc độ kinh doanh, **bước duyệt thủ công (Human-in-the-loop) là bắt buộc**.

1. Mở file: `.seo/data/clusters.json`
2. Kiểm tra các từ khóa trong từng cụm.
3. Tự do di chuyển, gộp (merge) hoặc tách (split) các cụm từ khóa nếu thấy thuật toán gom chưa hợp lý.
4. Lưu file sau khi chỉnh sửa xong.

## 📁 Dữ liệu & Lưu trữ

- **Dữ liệu phân cụm**: `.seo/data/clusters.json`
- **Dấu thời gian**: {thời gian hoàn tất}

---

💡 **Bước tiếp theo (Next Step):**
Sau khi bạn đã hoàn tất rà soát thủ công file JSON, hãy chạy lệnh:
👉 `/seo-research-topical-map` để AI bắt đầu gán Intent và định hình Topical Map.