description: "Research phase orchestrator: LLM Semantic Topical Mapping & Intent Assignment" version: "1.0"

/seo-research-topical-map

Purpose

Executes the LLM portion of Phase D: Topical Mapping. Takes the human-reviewed semantic clusters from clusters.json and uses LLM agents to evaluate, merge, and assign Intent Funnels, Core Entities, and Working Titles.

Đầu ra là file topical-map.json chứa cấu trúc tri thức chủ đề đã được định hình, chuẩn bị sẵn sàng cho khâu gán liên kết nội bộ cuối cùng.

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 clusters.json đã hoàn thành và được phê duyệt bởi người dùng (từ /seo-research-clustering).
• Có knowledge-graph.json để tham chiếu Core Entity.

Checkpointing & Session Recovery

💡 Khôi phục ngữ cảnh (Session Reset Recovery): Quy trình này có thể ngốn token khi biên tập các cụm lớn. Nếu cạn token, hệ thống sẽ khôi phục trực tiếp tiến trình từ các tệp TOON đã chia lô (assignment_input_{i}.toon).

Sub-Agent Coordination

• Primary Executor: @[topical-authority-planner] (builds the semantic topical map structures)
• Co-owner: @[site-architect] (validates silo taxonomies and hierarchy architecture)

Execution Flow

Step 1: Initial Cluster Mapping

• Chạy script Python để đọc clusters.json, sinh các tệp phân lô TOON và prompt gán thuộc tính ban đầu (Core Entity, Title, Funnel, Role) cho LLM.
• Lệnh: python .agents/skills/seo-plan/scripts/content_plan_generator.py {domain} --action prepare
• Outputs tạm:
  • .seo/data/content_plan_batches/assignment_input_{i}.toon (chứa gợi ý thực thể đa số suggested_entity)
  • .seo/data/content_plan_batches/assignment_generation_prompt.txt (ràng buộc thực thể theo danh sách chính thức từ Knowledge Graph)

Step 2: Editorial Review & Consolidation (LLM Step)

• Chạy script Python để hợp nhất các kết quả phân tích sơ bộ thành một bảng tổng quan đánh giá duy nhất.
• Lệnh: python .agents/skills/seo-plan/scripts/content_plan_generator.py {domain} --action prepare_review
• Outputs tạm:
  • .seo/data/content_plan_batches/plan_review_input.toon
  • .seo/data/content_plan_batches/plan_review_prompt.txt
• Hành động LLM: LLM (vai trò editor-in-chief) đọc dữ liệu đầu vào và thực hiện hợp nhất ý định tìm kiếm (Cannibalization) cùng rà soát phân phối vai trò bài viết. Trả về kết quả dưới định dạng TOON phẳng vào tệp plan_review_results.toon với cấu trúc [N]{cluster_id,merged_into_cluster_id,final_title,core_entity,intent_funnel,final_role}:.

Step 3: Export Topical Map

• Kịch bản Python sẽ đọc plan_review_results.toon và kết xuất ra file topical-map.json hoàn chỉnh.
• Lệnh: python .agents/skills/seo-keyword/scripts/topical_map_builder.py {domain} --action build-topical-map
• Cập nhật project.json.workflow_checkpoint with {workflow: "seo-research-topical-map", status: "completed"}.

💡 Không cần thiết lập Pause Gate tương tác ở đây, vì Orchestrator sẽ tự động chuyển giao đầu ra này cho /seo-content-plan để hoàn thành việc sinh Ma trận bài viết.

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 Topical Map — `{domain}`

**Trạng thái**: Hoàn tất định hình Cấu trúc Chủ đề (Phase 5/5)

## 📊 Tổng quan Topical Map

Hội đồng Biên tập (Editor-in-chief LLM) đã rà soát, gộp intent và hoàn thiện sơ đồ phân phối nội dung:

- **📦 Số cụm (Clusters) đã xử lý**: **{count}** cụm
- **🏷️ Số lượng Thực thể (Entities) được map**: **{entity_count}**
- **Cấu trúc phễu (Intent Funnel)**: *(Liệt kê nhanh tỷ lệ phân bổ TOFU, MOFU, BOFU nếu có thể trích xuất)*

## 🔍 Chất lượng & Tối ưu

- **Chống ăn thịt từ khóa (Cannibalization)**: Đã tự động gộp các cụm có ý định trùng lặp.
- **Vai trò bài viết (Role)**: Mỗi cụm đã được gán nhãn vai trò rõ ràng (Pillar, Cluster, Hỗ trợ, v.v.)
- *(Hiển thị 2-3 Working Titles tiêu biểu đã được LLM tối ưu)*

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

- **Bản đồ Topical Map cuối**: `.seo/data/topical-map.json`
- **Dấu thời gian**: {thời gian hoàn tất}

---

💡 **Bước tiếp theo (Next Step):**
Sơ đồ đã sẵn sàng để lập kế hoạch triển khai. Hãy chạy lệnh:
👉 `/seo-content-plan` để kết xuất Ma trận bài viết hoàn chỉnh.