aiox-core 5.0.2 → 5.0.4

package/pro/squads/squad-creator-pro/data/fusion-decision-points-analysis.md

@@ -0,0 +1,397 @@
+# 🔍 Análise Crítica: Pontos de Decisão no Squad Fusion
+
+> Revisão honesta: Onde REALMENTE precisa de julgamento vs mecânico puro?
+
+---
+
+## Princípio de Análise
+
+Para cada step, perguntar:
+1. **Existe ambiguidade?** Se sim → precisa interpretação
+2. **A decisão afeta qualidade?** Se sim → precisa julgamento
+3. **Regra determinística cobre 100% dos casos?** Se não → precisa fallback inteligente
+
+---
+
+## PHASE 1: DISCOVERY
+
+### ✅ WORKER: Contagem de arquivos
+```bash
+find squads/{squad}/agents -name '*.md' | wc -l
+```
+**Decisão?** Nenhuma. Puramente mecânico.
+
+### ⚠️ PRECISA REVISÃO: Entendimento do que cada squad FAZ
+
+**Problema identificado:**
+- Contar arquivos ✅
+- Entender o PROPÓSITO de cada squad ❌
+
+**Exemplo:**
+- `media-buy`: Foco em elite minds com frameworks
+- `media-squad`: Foco em operação multi-plataforma
+- `meta-ads`: Foco em compliance/auditoria
+
+**Pergunta crítica:** Como sei se dois squads são REALMENTE complementares ou têm overlap?
+
+**Decisão necessária:**
+- LLM precisa ler README/config de cada squad
+- Entender propósito, foco, diferenças
+- Identificar complementaridade vs redundância
+
+**Veredicto:** `discovery_purpose_analysis` = **Agent (LLM)**
+
+---
+
+## PHASE 2: DEDUPLICATION
+
+### ✅ WORKER: Exact match por nome
+```bash
+sort | uniq -d
+```
+
+### ⚠️ CRÍTICO: Semantic match - MUITO mais complexo que pensei
+
+**Cenários que NÃO são simples:**
+
+| Agent A | Agent B | São duplicatas? |
+|---------|---------|-----------------|
+| ads-analyst (media-squad) | ads-analyst (meta-ads) | **DEPENDE** - mesmo nome, mas propósitos diferentes? |
+| scale-optimizer (media-squad) | scale-optimizer (meta-ads) | **PRECISA LER** - um é genérico, outro é específico Meta? |
+| creative-analyst | creative-director | **NÃO** - funções diferentes |
+| traffic-manager | traffic-head | **TALVEZ** - precisa ver descrição |
+
+**Problema:** Mapa estático de sinônimos NÃO resolve. Precisa:
+1. Ler o conteúdo dos dois agents
+2. Comparar propósito, função, especialidade
+3. Decidir se são duplicatas, complementares, ou distintos
+
+**Veredicto:** `semantic_duplicate_analysis` = **Agent (LLM)** - para CADA par potencial
+
+### ⚠️ CRÍTICO: Escolher "melhor" versão
+
+**Minha simplificação anterior:** "Maior ganha"
+
+**Problema:** Linhas ≠ Qualidade
+
+**Cenários reais:**
+- Agent A: 500 linhas, mas genérico e superficial
+- Agent B: 350 linhas, mas focado e com frameworks reais
+
+**Critérios REAIS de qualidade:**
+1. Tem voice_dna bem definido?
+2. Tem output_examples REAIS (não placeholders)?
+3. Tem frameworks documentados?
+4. Tem anti_patterns?
+5. É baseado em mind real ou é genérico?
+6. Foi validado/testado?
+
+**Decisão necessária:**
+- LLM precisa ler AMBOS os agents
+- Avaliar qualidade em múltiplas dimensões
+- Recomendar qual manter (com rationale)
+
+**Veredicto:** `quality_comparison` = **Agent (LLM)**
+
+---
+
+## PHASE 3: SCOPE FILTERING
+
+### ⚠️ MAIS COMPLEXO: Keyword matching tem limites
+
+**Minha simplificação:** grep por keywords
+
+**Cenários problemáticos:**
+
+| Agent | Keywords encontradas | Pertence a paid_traffic? |
+|-------|---------------------|--------------------------|
+| automation-engineer | "automation" | **DEPENDE** - automação de quê? Ads? Email? |
+| research-head | "research" | **DEPENDE** - research de mercado? De audiência? |
+| cro-analyst | "conversion" | **SIM** - mas keyword não estava na lista |
+| content-scout-hormozi | "content" | **TALVEZ** - content para ads ou orgânico? |
+
+**Problema:** O NOME do agent não revela tudo. Precisa ler descrição/propósito.
+
+**Decisão necessária:**
+- Para agents ambíguos (score entre 0-2), LLM precisa:
+  1. Ler o agent completo
+  2. Entender sua função real
+  3. Decidir se pertence ao domínio
+
+**Veredicto:** `ambiguous_scope_decision` = **Agent (LLM)** ou **Hybrid**
+
+---
+
+## PHASE 4: COLLECTION
+
+### ✅ WORKER: Copiar arquivos não-conflitantes
+
+### ⚠️ CRÍTICO: Resolver conflitos
+
+**Minha simplificação:** "Maior ganha" ou "mover para _conflicts"
+
+**Cenários reais de conflito:**
+
+| Conflito | Decisão correta |
+|----------|-----------------|
+| Mesmo agent, versões diferentes | Qual é mais atual? Mais completo? |
+| Mesmo nome, funções diferentes | **NÃO MERGEAR** - renomear um |
+| Task com mesmo nome | Combinar? Escolher uma? |
+
+**Problema:** Conflitos precisam de análise caso a caso.
+
+**Opções:**
+1. **YOLO:** Sempre escolher do squad "mais confiável" (pré-definido)
+2. **QUALITY:** LLM analisa e recomenda
+
+**Veredicto:** `conflict_resolution` = **Worker (YOLO)** ou **Agent (QUALITY)**
+
+---
+
+## PHASE 5: VALIDATION
+
+### ✅ WORKER: Verificações estruturais
+- Arquivo existe e não está vazio
+- YAML válido
+- Seções obrigatórias presentes
+- Referências resolvem
+
+### ⚠️ NOVO INSIGHT: Validação de QUALIDADE
+
+**O que script NÃO consegue validar:**
+- O voice_dna faz sentido?
+- Os output_examples são realistas?
+- Os frameworks estão bem documentados?
+- O agent é coerente internamente?
+
+**Pergunta:** Queremos validar qualidade ou só estrutura?
+
+**Se só estrutura:** 100% Worker
+**Se qualidade:** Precisa LLM para sample check
+
+**Veredicto:** `quality_validation` = **Worker (estrutura)** + **Agent opcional (qualidade)**
+
+---
+
+## PHASE 6: STRUCTURE CREATION
+
+### ✅ WORKER: Criar diretórios, mover arquivos
+
+### ⚠️ CRÍTICO: Organizar Tiers
+
+**Minha simplificação:** "Herdar dos fontes"
+
+**Problema:** Squads fonte têm estruturas de tier DIFERENTES:
+
+```yaml
+# media-buy
+tier_0: [molly-pittman, depesh-mandalia]  # Diagnóstico
+tier_1: [kasim-aslam, tom-breeze]          # Platform Masters
+tier_2: [ralph-burns, pedro-sobral]        # Execution
+
+# meta-ads
+tier_0: [fiscal]                           # Auditoria
+tier_1: [ads-analyst]                      # Análise
+tier_2: [scale-optimizer]                  # Escala
+
+# media-squad
+# Não tem tiers, tem "diretores" e "executores"
+```
+
+**Decisão necessária:**
+- Como reconciliar estruturas diferentes?
+- Onde colocar agents novos que não existiam nos fontes?
+- Qual lógica de tier usar?
+
+**Veredicto:** `tier_organization` = **Agent (LLM)**
+
+### ⚠️ CRÍTICO: Definir Routing
+
+**Problema:** Routing é SEMÂNTICO, não mecânico.
+
+```yaml
+# Quando usar qual agent?
+meta_ads: [depesh-mandalia, nicholas-kusmich]  # POR QUÊ estes?
+google_ads: [kasim-aslam]                       # POR QUÊ só este?
+scaling: [ralph-burns, scale-optimizer]        # POR QUÊ estes dois?
+```
+
+**Decisão necessária:**
+- Entender especialidade de cada agent
+- Mapear para cenários de uso
+- Garantir cobertura completa
+
+**Veredicto:** `routing_definition` = **Agent (LLM)**
+
+### ⚠️ CRÍTICO: Criar Orchestrator
+
+**Não é template simples.** Orchestrator precisa:
+- Conhecer TODOS os agents do squad fusionado
+- Saber quando acionar cada um
+- Ter voice_dna próprio
+- Ter comandos que fazem sentido
+
+**Veredicto:** `orchestrator_creation` = **Agent (LLM)**
+
+---
+
+## PHASE 7: INTEGRATION TEST
+
+### ✅ WORKER: Verificações mecânicas
+- Orchestrator existe
+- Agents referenciados existem
+- Config YAML válido
+
+### ⚠️ OPCIONAL: Smoke test de comportamento
+- Ativar orchestrator e ver se responde bem
+- Testar um routing
+
+**Veredicto:** `structural_test` = **Worker**, `behavioral_test` = **Agent opcional**
+
+---
+
+## PHASE 8: CLEANUP
+
+### ✅ WORKER: Deletar após confirmação humana
+
+---
+
+## 📊 ANÁLISE REVISADA
+
+### Pontos de Decisão Identificados
+
+| ID | Decision Point | Tipo | Justificativa |
+|----|---------------|------|---------------|
+| D1 | Entender propósito de cada squad | **Agent** | Precisa ler e interpretar |
+| D2 | Identificar duplicatas semânticas | **Agent** | Nome ≠ função |
+| D3 | Comparar qualidade (não só linhas) | **Agent** | Múltiplos critérios subjetivos |
+| D4 | Classificar agents ambíguos no escopo | **Agent/Hybrid** | Keyword não resolve |
+| D5 | Resolver conflitos | **Agent (QUALITY)** | Análise caso a caso |
+| D6 | Organizar tiers | **Agent** | Reconciliar estruturas diferentes |
+| D7 | Definir routing | **Agent** | Semântico, não mecânico |
+| D8 | Criar orchestrator | **Agent** | Criativo, não template |
+
+### Distribuição REAL Revisada
+
+| Executor | Steps | % | Antes |
+|----------|-------|---|-------|
+| **Worker** | 42 | **71%** | 91.5% |
+| **Agent** | 12 | **20%** | 3.4% |
+| **Hybrid** | 4 | **7%** | 3.4% |
+| **Human** | 1 | **2%** | 1.7% |
+
+**Diferença:** 91.5% → 71% Worker. 20 pontos percentuais de LLM que eu tinha subestimado.
+
+---
+
+## 🎯 MAPA DE DECISÕES POR MODO
+
+### YOLO Mode (Mínima interação, aceita 60-75% qualidade)
+
+| Decision Point | Estratégia YOLO |
+|----------------|-----------------|
+| D1 (propósito) | Skip - assume complementares |
+| D2 (semantic dedup) | Usar mapa estático apenas |
+| D3 (qualidade) | Linhas + presença de seções |
+| D4 (escopo ambíguo) | Score >= 1 = inclui |
+| D5 (conflitos) | Squad com mais agents ganha |
+| D6 (tiers) | Herdar do squad principal |
+| D7 (routing) | Copiar do squad principal |
+| D8 (orchestrator) | Template genérico |
+
+**Worker em YOLO:** ~85%
+
+### QUALITY Mode (Checkpoints, 85-95% qualidade)
+
+| Decision Point | Estratégia QUALITY |
+|----------------|-------------------|
+| D1 (propósito) | **LLM analisa cada squad** |
+| D2 (semantic dedup) | **LLM compara pares** |
+| D3 (qualidade) | **LLM avalia ambos** |
+| D4 (escopo ambíguo) | **Hybrid: LLM + Human** |
+| D5 (conflitos) | **LLM recomenda + Human aprova** |
+| D6 (tiers) | **LLM propõe estrutura** |
+| D7 (routing) | **LLM define regras** |
+| D8 (orchestrator) | **LLM gera completo** |
+
+**Worker em QUALITY:** ~65%
+
+---
+
+## 🔧 ARQUITETURA REVISADA
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    FUSION WORKFLOW v3.0                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  MODE: YOLO                        MODE: QUALITY                │
+│  ┌─────────────────┐               ┌─────────────────┐         │
+│  │ Worker: 85%     │               │ Worker: 65%     │         │
+│  │ Agent:  10%     │               │ Agent:  25%     │         │
+│  │ Human:  5%      │               │ Human:  10%     │         │
+│  └─────────────────┘               └─────────────────┘         │
+│                                                                 │
+│  Qualidade: 60-75%                 Qualidade: 85-95%           │
+│  Tempo: ~15 min                    Tempo: ~45 min              │
+│  Custo: ~$3                        Custo: ~$15                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✅ CONCLUSÃO HONESTA
+
+### O que É 100% Worker (não precisa de LLM nunca):
+- Criar diretórios
+- Contar arquivos
+- Copiar/mover arquivos
+- Validar YAML syntax
+- Verificar arquivo existe
+- Verificar referência existe
+- Gerar relatórios (template + dados)
+- Backup/restore
+
+### O que PRECISA de LLM (pelo menos em QUALITY mode):
+- Entender propósito de um squad
+- Comparar dois agents semanticamente
+- Avaliar qualidade real (não só estrutura)
+- Decidir escopo de agents ambíguos
+- Resolver conflitos não-triviais
+- Organizar agents em tiers
+- Definir routing rules
+- Criar orchestrator
+
+### Recomendação Final
+
+**Para YOLO:** Criar scripts + heurísticas simples + LLM mínimo
+**Para QUALITY:** Scripts para mecânico + LLM para 8 decision points
+
+---
+
+## ✅ CORREÇÕES APLICADAS (2026-02-03)
+
+Todas as correções foram implementadas em `wf-squad-fusion.yaml` v2.1.0:
+
+### Bugs Corrigidos:
+1. ✅ Adicionado step `define_tiers` (Agent)
+2. ✅ Adicionado step `define_routing_rules` (Agent)
+3. ✅ Corrigido `create_orchestrator_if_needed` com prompt real
+
+### Executor Tags:
+- ✅ Todos os 56 steps agora têm `executor:` definido
+- ✅ Distribuição documentada no header do workflow
+
+### Distribuição Final Real:
+| Executor | Count | % |
+|----------|-------|---|
+| Worker | 44 | 79% |
+| Agent | 5 | 9% |
+| Hybrid | 6 | 11% |
+| Human | 1 | 1% |
+
+---
+
+*Análise revisada com honestidade sobre complexidade real*
+*Correções aplicadas após processo de `*optimize`*