@onion-architect-ai/cli 4.1.0-beta.1 → 4.1.0-beta.3

package/templates/.cursor/docs/architecture/acoplamento-clickup-problema-analise.md

@@ -0,0 +1,446 @@
+# 🔗 Problema de Acoplamento ClickUp nos Comandos
+
+## 📊 Situação Atual
+
+Os comandos de `engineer` e `product` contêm **amostras/exemplos de código MCP do ClickUp** misturados com a documentação, criando um nível alto de acoplamento.
+
+### Onde o Acoplamento Existe:
+
+```
+.cursor/commands/
+├── engineer/
+│   ├── work.md                 ← Contém exemplos de mcp_clickup_create_task_comment()
+│   ├── pr.md                   ← Contém exemplos de comentários formatados
+│   ├── pr-update.md            ← Contém exemplos de mcp_clickup_update_task()
+│   └── pre-pr.md               ← Contém templates de comentários
+│
+├── product/
+│   ├── task.md                 ← Contém exemplos JavaScript de mcp_clickup_create_task()
+│   ├── presentation.md         ← Contém chamadas mcp_clickup_get_task()
+│   └── checklist-sync.md       ← Pseudocódigo de ClickUp
+```
+
+---
+
+## ❌ Problemas Causados
+
+### 1. **Acoplamento Semântico**
+- Comandos ficam "tightly coupled" à API do ClickUp
+- Se API mudar, precisa atualizar múltiplos comandos
+- Documentação fica poluidá com código técnico
+
+### 2. **Duplicação de Conhecimento**
+- Padrões de comentários definidos em múltiplos lugares:
+  - `/engineer/work.md` - Template de comentário
+  - `/engineer/pr.md` - Template de comentário
+  - `/engineer/pre-pr.md` - Template de comentário
+  - `/engineer/pr-update.md` - Template de comentário
+  - `.cursor/docs/clickup/*.md` - Mais templates
+
+### 3. **Difícil Manutenção**
+```
+Cenário: Precisa mudar formato dos separadores
+├── Mude em work.md ✓
+├── Mude em pr.md ✓
+├── Mude em pr-update.md ✓
+├── Mude em pre-pr.md ✓
+├── Mude em dual-comment-strategy.md ✓
+├── Mude em separador-tamanho-otimizado.md ✓
+└── Risco de inconsistência entre mudanças! ⚠️
+```
+
+### 4. **Falta de Separação de Responsabilidades**
+```
+engineer/work.md atual:
+├── Lógica de fluxo de desenvolvimento ✓ (correto)
+├── Estrutura de fases ✓ (correto)
+├── Templates de comentários ClickUp ✗ (acoplado!)
+├── Padrões formatação Unicode ✗ (acoplado!)
+└── Exemplo de mcp_clickup_create_task_comment() ✗ (acoplado!)
+```
+
+### 5. **Difícil Testar Mudanças**
+- Ao fazer mudança em padrão de comentário
+- Precisa testar em 5+ lugares
+- Risco alto de regressão
+
+### 6. **Documentação Poluída**
+- Comandos focam em "O que fazer" (business logic)
+- Mas também contêm "Como fazê-lo" (implementação técnica)
+- Fica difícil ler e entender propósito principal
+
+---
+
+## 🎯 Raiz do Problema
+
+O acoplamento surgiu porque:
+
+1. **Falta de abstração** - Não há uma camada de abstração para ClickUp
+2. **Proximidade documentação + código** - Docs têm exemplos de implementação
+3. **Padrões espalhados** - Templates não têm "source of truth"
+4. **Sem centralização** - Cada comando define seu próprio padrão
+
+---
+
+## ✅ Solução Proposta: 3 Camadas de Arquitetura
+
+### Arquitetura Ideal:
+
+```
+┌─────────────────────────────────────────────────────┐
+│ CAMADA 1: Comandos (Orquestração)                   │
+│ /engineer/work.md, /product/task.md, etc.          │
+│ RESPONSABILIDADE: "O que fazer" (business logic)    │
+│ FOCO: Workflow, decisões, próximos passos          │
+└────────────────────┬────────────────────────────────┘
+                     │
+                     ↓
+┌─────────────────────────────────────────────────────┐
+│ CAMADA 2: Estratégias (Padrões + Templates)        │
+│ .cursor/docs/strategies/                            │
+│ RESPONSABILIDADE: "Como fazê-lo"                    │
+│ FOCO: Padrões, templates, formato de comentários   │
+└────────────────────┬────────────────────────────────┘
+                     │
+                     ↓
+┌─────────────────────────────────────────────────────┐
+│ CAMADA 3: Utilitários (Abstrações MCP)             │
+│ .cursor/utils/clickup-mcp-wrappers/                │
+│ RESPONSABILIDADE: Chamar MCP do ClickUp            │
+│ FOCO: Encapsular chamadas API, tratamento erro    │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔧 Implementação da Solução
+
+### ANTES (Acoplado):
+
+```markdown
+# engineer/work.md
+
+Quando uma fase é completada, adicionar comentário:
+
+\`\`\`typescript
+const detailedComment = `🔧 FASE COMPLETADA: ${phaseName}
+
+━━━━━━━━━━━━━━
+
+📁 ARQUIVOS MODIFICADOS:
+   ∟ ${file1}
+   ...
+`;
+
+await mcp_clickup_create_task_comment({
+  task_id: subtaskId,
+  comment_text: detailedComment
+});
+\`\`\`
+```
+
+**Problemas:**
+- ❌ Comando contém lógica de formatação
+- ❌ Mistura orquestração com implementação
+- ❌ Duplicado em 4 outros comandos
+
+---
+
+### DEPOIS (Desacoplado):
+
+**1. Estratégia centralizada:**
+
+```markdown
+# .cursor/docs/strategies/clickup-comment-patterns.md
+
+## Padrão: Comentário Detalhado de Fase Completada
+
+```typescript
+const pattern = {
+  title: "FASE COMPLETADA",
+  sections: [
+    { icon: "🔧", key: "FASE_COMPLETADA", title: "Nome da Fase" },
+    { icon: "📁", key: "ARQUIVOS_MODIFICADOS", title: "Lista de arquivos" },
+    { icon: "🔧", key: "IMPLEMENTACOES", title: "O que foi implementado" },
+    ...
+  ],
+  separator: "━━━━━━━━━━━━━━"
+};
+```
+```
+
+**2. Wrapper MCP centralizado:**
+
+```typescript
+// .cursor/utils/clickup-mcp-wrappers.ts
+
+export async function commentPhaseCompletion(
+  subtaskId: string,
+  phaseData: PhaseInfo
+): Promise<void> {
+  const comment = buildDetailedPhaseComment(phaseData);
+  await mcp_clickup_create_task_comment({
+    task_id: subtaskId,
+    comment_text: comment
+  });
+}
+```
+
+**3. Comando limpo:**
+
+```markdown
+# engineer/work.md
+
+Quando uma fase é completada:
+- Chamar wrapper: `commentPhaseCompletion(subtaskId, phaseData)`
+- Sistema automaticamente gera comentário formatado
+- Atualiza status da subtask
+- Adiciona comentário resumido na task principal
+```
+
+---
+
+## 📋 Benefícios da Solução
+
+### 1. **Separação de Responsabilidades** ✅
+```
+engineer/work.md:    Apenas orquestração
+strategies/:         Padrões e templates
+utils/clickup-*:     Implementação MCP
+```
+
+### 2. **Fácil Manutenção** ✅
+```
+Mudança de formato de comentário:
+- Altera APENAS em strategies/clickup-comment-patterns.md
+- Todos os comandos automaticamente usam novo padrão
+```
+
+### 3. **Zero Duplicação** ✅
+```
+ANTES:
+- 4 templates diferentes em 4 arquivos
+- Risco de inconsistência
+
+DEPOIS:
+- 1 template em 1 lugar (source of truth)
+- Todos os comandos usam o mesmo
+```
+
+### 4. **Testabilidade** ✅
+```
+Pode testar mudanças:
+- Em um só lugar
+- Com confiança
+- Sem risco de breaking em 5 comandos
+```
+
+### 5. **Documentação Limpa** ✅
+```
+engineer/work.md fica focado em:
+- Fluxo de trabalho
+- Decisões de negócio
+- Próximos passos
+
+NÃO contém:
+- Código MCP
+- Formatos de comentário
+- Exemplos implementação
+```
+
+---
+
+## 🗂️ Estrutura Proposta
+
+### Criar Nova Estrutura:
+
+```
+.cursor/
+├── utils/
+│   └── clickup-mcp-wrappers.md        ← NOVO: Abstrações MCP
+│       └── Seções:
+│           - commentPhaseCompletion()
+│           - updateTaskStatus()
+│           - createDetailedComment()
+│           - createSummaryComment()
+│           - etc.
+│
+├── docs/
+│   ├── strategies/                     ← NOVO: Padrões centralizados
+│   │   └── clickup-comment-patterns.md ← Todos os templates
+│   │       - Padrão: Fase completada
+│   │       - Padrão: Validação de PR
+│   │       - Padrão: Update de PR
+│   │       - etc.
+│   │
+│   └── clickup/
+│       └── Mantém apenas:
+│           - Documentação conceitual
+│           - Decisões arquiteturais
+│           - Não contém implementação
+```
+
+---
+
+## 📝 Refatoração Passo a Passo
+
+### Fase 1: Criar Abstrações
+- [ ] Criar `.cursor/utils/clickup-mcp-wrappers.md`
+- [ ] Documentar todas as abstrações necessárias
+- [ ] Criar wrappers para operações comuns
+
+### Fase 2: Centralizar Padrões
+- [ ] Criar `.cursor/docs/strategies/clickup-comment-patterns.md`
+- [ ] Migrar TODOS os templates de comentário
+- [ ] Remover duplicatas de outros arquivos
+
+### Fase 3: Refatorar Comandos
+- [ ] `engineer/work.md` - Remover exemplos MCP
+- [ ] `engineer/pr.md` - Remover exemplos MCP
+- [ ] `engineer/pre-pr.md` - Remover exemplos MCP
+- [ ] `engineer/pr-update.md` - Remover exemplos MCP
+- [ ] `product/task.md` - Remover exemplos MCP
+
+### Fase 4: Atualizar Documentação
+- [ ] Atualizar `.cursor/docs/clickup/clickup-*.md`
+- [ ] Remover implementação técnica
+- [ ] Manter apenas conceitos e decisões
+
+### Fase 5: Validação
+- [ ] Testar que comandos ainda funcionam
+- [ ] Verificar consistência de comentários
+- [ ] Validar que documentação fica clara
+
+---
+
+## 🎯 Checklist de Desacoplamento
+
+Para cada comando (`engineer/work.md`, `engineer/pr.md`, etc):
+
+- [ ] Remove exemplos de `mcp_clickup_*`
+- [ ] Remove templates de comentários inline
+- [ ] Remove pseudocódigo de implementação
+- [ ] Referencia abstrações centralizadas
+- [ ] Fica focado em "o que fazer"
+- [ ] Fica claro e legível
+
+---
+
+## 💡 Exemplo Prático Completo
+
+### ANTES (Acoplado):
+
+```markdown
+# /engineer/work.md
+
+## 💬 Estratégia DUAL de Comentários
+
+```typescript
+const detailedComment = `🔧 FASE COMPLETADA: ${phaseName}
+
+━━━━━━━━━━━━━━
+
+📁 ARQUIVOS MODIFICADOS:
+   ∟ ${file1}
+   ∟ ${file2}
+
+🔧 IMPLEMENTAÇÕES:
+   ▶ ${impl1}
+   ▶ ${impl2}
+
+...
+
+━━━━━━━━━━━━━━
+
+⏰ Completado: ${timestamp} | 🎯 Status: Done`;
+
+// 1. Comentário DETALHADO na SUBTASK
+await mcp_clickup_create_task_comment({
+  task_id: subtaskId,
+  comment_text: detailedComment
+});
+
+// 2. Atualizar STATUS da SUBTASK
+await mcp_clickup_update_task({
+  task_id: subtaskId,
+  status: 'Done'
+});
+
+// 3. Comentário RESUMIDO na TASK PRINCIPAL
+await mcp_clickup_create_task_comment({
+  task_id: mainTaskId,
+  comment_text: summaryComment
+});
+```
+```
+
+---
+
+### DEPOIS (Desacoplado):
+
+```markdown
+# /engineer/work.md
+
+## 💬 Estratégia DUAL de Comentários
+
+Quando uma fase é completada, o sistema automaticamente:
+
+1. **Comentário detalhado na subtask** 
+   - Contém contexto técnico completo
+   - Usa padrão de: `.cursor/docs/strategies/clickup-comment-patterns.md`
+   - Gerado por: `.cursor/utils/clickup-mcp-wrappers.md` → `commentPhaseCompletion()`
+
+2. **Atualiza status da subtask para Done**
+   - Status automaticamente atualizado
+
+3. **Comentário resumido na task principal**
+   - Contém apenas progresso executivo
+   - Usa padrão de: `.cursor/docs/strategies/clickup-comment-patterns.md`
+   - Gerado por: `.cursor/utils/clickup-mcp-wrappers.md` → `commentProgressUpdate()`
+
+**Para detalhes técnicos**, ver:
+- Padrões em `.cursor/docs/strategies/clickup-comment-patterns.md`
+- Implementação em `.cursor/utils/clickup-mcp-wrappers.md`
+```
+
+**Resultado:**
+- ✅ `engineer/work.md` focado em orquestração
+- ✅ Implementação técnica centralizada
+- ✅ Fácil entender propósito do comando
+- ✅ Fácil manter padrões em um só lugar
+
+---
+
+## 🚀 Benefício Esperado
+
+```
+ANTES (Acoplado):
+├── 5 exemplos de commentário espalhados
+├── 4 templates duplicados
+├── Comando + implementação misturados
+└── ❌ Difícil manter e evoluir
+
+DEPOIS (Desacoplado):
+├── 1 fonte de verdade para padrões
+├── Abstrações reutilizáveis
+├── Comando focado em negócio
+├── Implementação centralizada
+└── ✅ Fácil manter, testar e evoluir
+```
+
+---
+
+## 📚 Referências
+
+- Single Responsibility Principle (SRP)
+- Separation of Concerns (SOC)
+- DRY (Don't Repeat Yourself)
+- Abstraction Pattern
+
+---
+
+**Status**: Análise completa e solução detalhada  
+**Prioridade**: ALTA - Acoplamento é dívida técnica  
+**Impacto**: Manutenibilidade significativamente melhorada  
+**Esforço**: Médio (5-8 horas para refatoração completa)
+