whole-regrouper

name	whole-regrouper
description	Phân tích, gom nhóm, và ĐỒNG BỘ THÔNG MINH giữa Tổng Quan listing và actual group headers. v5.1.0: Intelligent Analysis with agent integration - phân tích thực sự cả hai với hỗ trợ từ specialized agents.
version	5.1.0
license	MIT
allowed-tools	["Edit","Grep","Read","Bash","Task"]
metadata	{"author":"Whole Project","category":"documentation","updated":"2026-01-02"}

Whole Concept Regrouper & Reconciler v5.1

Intelligent Analysis with Agent Integration - Phân tích thực sự cả hai groupings với hỗ trợ từ specialized agents.

---

Core Philosophy

KHÔNG giả định grouping nào tốt hơn.

Mỗi CHỨC NĂNG có TWO representations:

1. Tổng Quan listing - Overview với group names và concept counts
2. Content headers - Actual ### headers với #### concepts bên dưới

Cả hai có thể có điểm mạnh riêng:

• Tổng Quan có thể có grouping logic tốt hơn (coherent, mental model rõ)
• Content có thể có chi tiết chính xác hơn (accurate to actual concepts)

→ Phân tích cả hai, quyết định có căn cứ.

---

Analysis Criteria

1. Coherence (Mạch lạc) - Weight: HIGH

• Các concepts trong nhóm có chung chủ đề?
• Có thể giải thích "đều về..." trong 1 câu?
• Có concept "lạc lõng"?

2. Balance (Cân bằng) - Weight: MEDIUM

• Per group: 3-8 concepts (ideal: 5-6)
• Không có groups quá lớn (>10) hoặc quá nhỏ (<2)

3. Natural Thinking (Tự nhiên) - Weight: HIGH

• Phù hợp mental model của người dùng?
• Tên nhóm gợi nhớ ngay nội dung?

4. Accuracy (Chính xác) - Weight: MEDIUM

• Tên nhóm mô tả chính xác nội dung?
• Số concepts match?
• Concept names chính xác?

---

Strategy Options

[A] Tổng Quan → Content
    Tổng Quan có grouping logic TỐT HƠN
    → Reorganize content để match Tổng Quan

[B] Content → Tổng Quan
    Content có chi tiết CHÍNH XÁC HƠN
    → Update Tổng Quan listing để match actual

[C] Full Regroup
    CẢ HAI ĐỀU CÓ VẤN ĐỀ
    → Cần phân tích lại từ đầu với /regroup

[H] Hybrid Merge
    MỖI BÊN CÓ ĐIỂM MẠNH RIÊNG
    → Lấy groups tốt nhất từ cả hai
    → Chỉ định: "Group 1,3 from Tổng Quan + Group 2,4 from Content"

[S] Skip - Already Synced
    Hai bên ĐÃ ĐỒNG BỘ
    → Không cần thay đổi

---

Decision Framework

Priority order khi conflict:

1. Coherence > Balance

   • Grouping logic quan trọng hơn size

2. Natural Thinking > Accuracy

   • User experience > technical correctness

3. Khi tie → Consider Hybrid [H]

   • Lấy best of both worlds

4. Khi cả hai < 3 sao → Full Regroup [C]

   • Cần làm lại từ đầu

---

Integration with Agents

When to Invoke Agents

Use Task tool to invoke specialized agents for deep analysis during regrouping:

// For semantic grouping analysis and duplicate detection
Task(subagent_type: 'whole-translator',
     prompt: 'Analyze semantic coherence and cultural grouping for CF[N] concepts')

// For cross-reference validation after regrouping
Task(subagent_type: 'whole-cross-reference',
     prompt: 'Validate and update cross-references after regrouping CF[N]')

// For structure validation before commit
Task(subagent_type: 'whole-content-validator',
     prompt: 'Validate regrouped structure and compliance for CF[N]')

When NOT to Use Agents

• Simple reconciliation (strategy [S] - already synced) → Direct comparison
• Balance checks (counting concepts) → Use Grep/scripts
• Format validation → Use validation scripts in scripts/
• Single group rename → Direct Edit

---

Agent Integration Guide

whole-translator

When to use: Semantic coherence analysis for grouping decisions Command: Task(subagent_type='whole-translator', prompt='Analyze semantic grouping coherence for CF[N]') Expected output: Semantic similarity analysis, cultural grouping recommendations

whole-cross-reference

When to use: Validate cross-references after major regrouping Command: Task(subagent_type='whole-cross-reference', prompt='Validate cross-references after CF[N] regroup') Expected output: Cross-reference validation report, orphaned links detection

whole-content-validator

When to use: Final validation before committing regrouped content Command: Task(subagent_type='whole-content-validator', prompt='Validate regrouped CF[N] structure') Expected output: Structure validation report, compliance check

---

Workflow

/reconcile [N]

Phase 1: LOCATE & READ
├─ Grep "## CHỨC NĂNG" → boundaries
└─ Read section content

Phase 2: PARSE BOTH
├─ A: Tổng Quan listing
└─ B: Content headers + concepts

Phase 3: ANALYZE
├─ Score each grouping on 4 criteria
├─ Compare winner per criterion
└─ Calculate overall score

Phase 4: RECOMMEND
├─ Reasoned recommendation [A/B/C/H]
├─ Explain trade-offs
└─ Ask for confirmation

Phase 5: EXECUTE
├─ Apply chosen strategy
├─ Validate changes
└─ Auto commit & push

/regroup [N]

Full regroup workflow khi cần phân tích lại từ đầu.

---

Scoring Output Format

╔═══════════════════════════════════════════════╗
║ ANALYSIS: CF[N] - [Function Name]             ║
╠═══════════════════════════════════════════════╣
║                                               ║
║ TỔNG QUAN: [M] groups                         ║
║ Coherence: ⭐⭐⭐⭐☆ | Balance: ⭐⭐⭐☆☆        ║
║ Natural: ⭐⭐⭐⭐⭐ | Accuracy: ⭐⭐⭐☆☆         ║
║                                               ║
║ CONTENT: [M] groups                           ║
║ Coherence: ⭐⭐⭐☆☆ | Balance: ⭐⭐⭐⭐☆        ║
║ Natural: ⭐⭐⭐☆☆ | Accuracy: ⭐⭐⭐⭐⭐         ║
║                                               ║
╠═══════════════════════════════════════════════╣
║ RECOMMENDATION: [A/B/C/H] - [Reasoning]       ║
╚═══════════════════════════════════════════════╝

---

Critical Rules

✅ MUST

• Phân tích thực sự cả hai groupings (analyze both, don't assume)
• Cho điểm có căn cứ (score with evidence)
• Giải thích reasoning (explain trade-offs)
• Preserve all content (only add, never subtract)
• Use agents for deep semantic analysis when needed
• Validate with whole-content-validator before commit
• Use shared utilities from .claude/skills/shared
• Update cross-references after major regrouping

❌ NEVER

• Giả định một bên luôn đúng (assume one side is always right)
• Skip analysis phase
• Delete concepts or modify concept content
• Commit without validation (use scripts or agents)
• Ignore cross-reference integrity
• Use agents for simple tasks (prefer scripts)

---

Commands

• /reconcile [N] - Intelligent reconcile single CHỨC NĂNG
• /reconcile - Auto-detect next pending
• /regroup [N] - Full regroup when reconcile isn't enough

---

References

Load as needed:

• references/grouping-principles.md - Criteria details
• references/naming-guidelines.md - Naming standards
• references/quality-checklist.md - Validation checklist

---

Version: 5.1.0 | Philosophy: Analyze first, decide with reasoning, validate with agents