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:

Tổng Quan listing - Overview với group names và concept counts
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:

Coherence > Balance
- Grouping logic quan trọng hơn size
Natural Thinking > Accuracy
- User experience > technical correctness
Khi tie → Consider Hybrid [H]
- Lấy best of both worlds
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

whole-regrouper

$ Installer