up-cc 0.2.3 → 0.3.1

package/templates/report.md

@@ -0,0 +1,177 @@
+# Template de Relatorio Consolidado
+
+Template para o relatorio consolidado produzido pelo sintetizador apos receber sugestoes de todos os agentes auditores. Organiza sugestoes em matriz 2x2 de esforco x impacto.
+
+<template>
+
+```markdown
+---
+projeto: [nome do projeto]
+data: [YYYY-MM-DD]
+stack: [stack detectada]
+agentes: [lista de agentes que contribuiram]
+total_sugestoes: [N]
+cobertura: [X arquivos analisados de Y total]
+---
+
+# Relatorio de [Melhorias|Ideias]: [Nome do Projeto]
+
+## Sumario Executivo
+
+[2-3 paragrafos resumindo: estado geral do codebase, areas de maior preocupacao, distribuicao de sugestoes por dimensao, recomendacao de por onde comecar]
+
+## Visao Geral
+
+| Dimensao | Sugestoes | Quick Wins | Estrategicos | Preenchimentos | Evitar |
+|----------|-----------|------------|--------------|----------------|--------|
+| UX | N | N | N | N | N |
+| Performance | N | N | N | N | N |
+| Modernidade | N | N | N | N | N |
+| Codigo | N | N | N | N | N |
+| Ideias | N | N | N | N | N |
+| **Total** | **N** | **N** | **N** | **N** | **N** |
+
+## Matriz Esforco x Impacto
+
+### Quick Wins (Baixo Esforco + Alto Impacto)
+> Implementar primeiro. Maior retorno por tempo investido.
+
+[Lista de sugestoes no formato padrao de suggestion.md, ordenadas por impacto decrescente]
+
+### Projetos Estrategicos (Alto Esforco + Alto Impacto)
+> Planejar com cuidado. Alto valor mas requer investimento significativo.
+
+[Lista de sugestoes no formato padrao de suggestion.md, ordenadas por impacto decrescente]
+
+### Preenchimentos (Baixo Esforco + Baixo Impacto)
+> Fazer quando houver tempo. Melhorias incrementais.
+
+[Lista de sugestoes no formato padrao de suggestion.md, ordenadas por impacto decrescente]
+
+### Evitar (Alto Esforco + Baixo Impacto)
+> Nao priorizar. Custo-beneficio desfavoravel.
+
+[Lista de sugestoes no formato padrao de suggestion.md, ordenadas por impacto decrescente]
+
+## Cobertura
+
+### Arquivos Analisados
+[Lista de TODOS os arquivos que foram analisados, agrupados por diretorio]
+
+### Arquivos Nao Analisados
+[Arquivos excluidos com razao: binario, gerado, vendor, etc.]
+
+### Porcentagem de Cobertura
+[X de Y arquivos = Z%]
+
+## Conflitos entre Dimensoes
+[Sugestoes que conflitam entre dimensoes, com recomendacao de qual priorizar e por que]
+(Ex: "PERF-005 sugere remover animacoes, UX-012 sugere manter -- Recomendacao: manter com prefers-reduced-motion")
+
+Se nao houver conflitos, omitir esta secao.
+
+## Proximos Passos
+[3-5 acoes concretas recomendadas para comecar, baseadas nos quick wins de maior impacto]
+```
+
+</template>
+
+<quadrant_definitions>
+
+### Regras de Classificacao nos Quadrantes
+
+A classificacao usa os campos Esforco e Impacto de cada sugestao (template suggestion.md):
+
+|  | Impacto M/G (Alto) | Impacto P (Baixo) |
+|---|---|---|
+| **Esforco P (Baixo)** | Quick Wins | Preenchimentos |
+| **Esforco M/G (Alto)** | Projetos Estrategicos | Evitar |
+
+**Mapeamento P/M/G para a matriz:**
+- `P` (Pequeno) = Baixo
+- `M` (Medio) = Alto
+- `G` (Grande) = Alto
+
+M e G sao agrupados no mesmo lado da matriz (alto).
+
+**Regra de empate (ambos M):**
+Se Esforco=M e Impacto=M, classificar como **Projetos Estrategicos** (abordagem conservadora -- assume alto custo quando ambiguo).
+
+**Ordenacao dentro de cada quadrante:**
+1. Impacto decrescente (G antes de M)
+2. Em caso de empate de impacto, Esforco crescente (P antes de M)
+
+### Tabela Completa de Classificacao
+
+| Esforco | Impacto | Quadrante |
+|---------|---------|-----------|
+| P | G | Quick Wins |
+| P | M | Quick Wins |
+| P | P | Preenchimentos |
+| M | G | Projetos Estrategicos |
+| M | M | Projetos Estrategicos |
+| M | P | Evitar |
+| G | G | Projetos Estrategicos |
+| G | M | Projetos Estrategicos |
+| G | P | Evitar |
+
+</quadrant_definitions>
+
+<guidelines>
+
+### Orientacoes de Preenchimento
+
+**Responsabilidade:**
+- O sintetizador (Fase 6) e responsavel por preencher este template
+- Para /up:melhorias, o arquivo e salvo em `.plano/melhorias/RELATORIO.md`
+- Para /up:ideias, o arquivo e salvo em `.plano/ideias/RELATORIO.md`
+
+**Deduplicacao:**
+- Sugestoes duplicadas entre dimensoes DEVEM ser mescladas antes de classificar
+- Manter a sugestao mais completa
+- Listar dimensoes originais entre parenteses: `Performance (UX)` ou `Modernidade (Performance)`
+- O ID da sugestao mantida prevalece; a outra vira referencia: "Ver PERF-005"
+
+**Sumario Executivo:**
+- DEVE ser opinativo -- recomendar por onde comecar, nao apenas listar
+- Mencionar as 2-3 areas de maior preocupacao
+- Indicar se o codebase esta em bom estado geral ou precisa de atencao urgente
+- Terminar com recomendacao clara de proximos passos
+
+**Tabela de Visao Geral:**
+- Total na ultima linha deve bater com soma das linhas anteriores
+- Total de cada coluna de quadrante deve bater com o total de sugestoes daquele quadrante
+- Se uma dimensao nao tem sugestoes, manter a linha com zeros
+
+**Secao de Conflitos:**
+- So aparece se houver conflitos reais entre dimensoes
+- Nao forcar conflitos onde nao existem
+- Cada conflito deve ter recomendacao de resolucao
+
+**Frontmatter YAML:**
+- Obrigatorio -- permite parsing programatico futuro
+- O campo `cobertura` prepara INFRA-03 (implementado na Fase 5)
+- O campo `agentes` lista os nomes dos agentes que contribuiram sugestoes
+
+**Consistencia:**
+- Sugestoes dentro dos quadrantes usam o formato exato de suggestion.md
+- Nenhuma sugestao pode aparecer em mais de um quadrante
+- Toda sugestao recebida dos agentes deve aparecer em exatamente um quadrante
+
+</guidelines>
+
+<evolution>
+
+### Ciclo de Vida do Template
+
+**Fase 3 (atual):** Template criado como infraestrutura. Define formato e regras.
+
+**Fase 5:** Agentes auditores (UX, Performance, Modernidade) preenchem sugestoes individuais usando suggestion.md. Cada agente produz sua lista de sugestoes.
+
+**Fase 6:** Sintetizador recebe sugestoes de todos os agentes, deduplica, resolve conflitos, classifica nos quadrantes e preenche este template de relatorio.
+
+**Fase 7/9:** Workflow de /up:melhorias e /up:ideias orquestra agentes e apresenta o relatorio final ao usuario.
+
+**Fase 10:** Sugestoes aprovadas pelo usuario sao convertidas em fases no ROADMAP.md. O campo ID de cada sugestao permite rastreabilidade de sugestao -> fase.
+
+</evolution>

package/templates/suggestion.md

@@ -0,0 +1,152 @@
+# Template de Sugestao
+
+Template para sugestoes individuais produzidas por agentes auditores e idealizadores. Cada sugestao e um bloco autocontido com formato padrao para agregacao e priorizacao.
+
+<template>
+
+```markdown
+### [ID]: [titulo curto do problema]
+
+| Campo | Valor |
+|-------|-------|
+| Arquivo | `caminho/do/arquivo.ext` |
+| Linha | 42 (ou range 42-58, ou N/A para problemas estruturais) |
+| Dimensao | UX / Performance / Modernidade / Codigo / Ideias |
+| Esforco | P / M / G |
+| Impacto | P / M / G |
+
+**Problema:** Descricao concreta do problema encontrado, com evidencia do codigo.
+
+**Sugestao:** Acao especifica para resolver, com exemplo de codigo se aplicavel.
+
+**Referencia:** Link ou nome do padrao/best practice que fundamenta a sugestao (opcional mas recomendado).
+```
+
+</template>
+
+<field_definitions>
+
+### Campos Obrigatorios
+
+**ID**
+Formato `[DIM]-[NNN]` onde DIM e abreviatura da dimensao e NNN e sequencial por dimensao.
+Abreviaturas: `UX`, `PERF`, `MOD`, `COD`, `IDEA`.
+Exemplos: `PERF-003`, `UX-012`, `MOD-001`.
+IDs sao sequenciais dentro de cada dimensao, resetados por relatorio.
+
+**Arquivo**
+Caminho relativo a raiz do projeto. NUNCA generico ("varios arquivos").
+Se afetar multiplos arquivos, criar uma sugestao para o arquivo mais representativo e notar "Afeta tambem: arquivo2.ext, arquivo3.ext" na descricao do problema.
+
+**Linha**
+Numero de linha ou range (ex: `42`, `42-58`).
+Use `N/A` apenas para problemas estruturais (ex: "falta de testes", "ausencia de arquivo de config").
+
+**Dimensao**
+Categoria da analise que originou o finding. Valores fixos:
+- `UX` -- Usabilidade, acessibilidade, experiencia do usuario
+- `Performance` -- Velocidade, eficiencia, otimizacao
+- `Modernidade` -- Padroes atuais, dependencias, compatibilidade
+- `Codigo` -- Qualidade, legibilidade, manutencao
+- `Ideias` -- Features novas, melhorias funcionais
+
+Um finding pode ter tag secundaria entre parenteses: `Performance (UX)` se impacta ambas dimensoes.
+
+**Esforco**
+Estimativa de trabalho para implementar:
+- `P` (Pequeno) -- Menos de 30 minutos. Rename, config, import, ajuste pontual.
+- `M` (Medio) -- 30 minutos a 2 horas. Refatorar funcao, adicionar componente, ajustar modulo.
+- `G` (Grande) -- Mais de 2 horas. Reescrever modulo, migrar dependencia, reestruturar.
+
+Se Esforco=G, a justificativa DEVE aparecer no campo Sugestao.
+
+**Impacto**
+Beneficio esperado se implementado:
+- `P` (Pequeno) -- Melhoria marginal, nice-to-have.
+- `M` (Medio) -- Melhoria notavel para usuario ou desenvolvedor.
+- `G` (Grande) -- Melhoria critica, resolve dor real.
+
+### Campo Obrigatorio Condicional
+
+**Problema**
+DEVE conter evidencia concreta: trecho de codigo, metrica, sintoma observavel.
+NAO aceitar descricoes vagas como "codigo poderia melhorar" ou "nao esta bom".
+
+**Sugestao**
+DEVE ser acao implementavel. Incluir exemplo de codigo quando possivel.
+NAO aceitar "considerar melhorar X" -- deve ser "trocar X por Y porque Z".
+
+### Campo Opcional (Recomendado)
+
+**Referencia**
+Padrao, documentacao ou best practice que fundamenta a sugestao.
+Exemplos: "React docs: useMemo", "Web Vitals: CLS", "OWASP Top 10: A03", "MDN: Intersection Observer".
+
+</field_definitions>
+
+<guidelines>
+
+### Orientacoes de Preenchimento
+
+- Cada agente auditor produz uma lista de sugestoes neste formato
+- IDs sao sequenciais dentro de cada dimensao, resetados por relatorio
+- Sugestoes devem ser autocontidas -- quem le uma sugestao individual entende o problema e a solucao sem contexto externo
+- Se uma sugestao depende de outra, referenciar o ID: "Prerequisito: PERF-001"
+- Maximo 1 sugestao por bloco. Nunca agrupar problemas distintos
+- Se o mesmo padrao aparece em N arquivos, criar 1 sugestao para o arquivo mais representativo e notar "Afeta tambem: arquivo2.ext, arquivo3.ext" na descricao do problema
+- Ordenar sugestoes por impacto decrescente dentro de cada dimensao
+
+### Exemplo Completo
+
+```markdown
+### PERF-003: Re-render desnecessario em lista de produtos
+
+| Campo | Valor |
+|-------|-------|
+| Arquivo | `src/components/ProductList.tsx` |
+| Linha | 24-38 |
+| Dimensao | Performance (UX) |
+| Esforco | P |
+| Impacto | M |
+
+**Problema:** O componente `ProductList` recria o array filtrado a cada render porque `products.filter()` e chamado diretamente no JSX (linha 31). Com 500+ produtos, causa jank visivel ao digitar no campo de busca.
+
+**Sugestao:** Envolver o filtro em `useMemo` com dependencia em `[products, searchTerm]`:
+\```tsx
+const filtered = useMemo(
+  () => products.filter(p => p.name.includes(searchTerm)),
+  [products, searchTerm]
+);
+\```
+
+**Referencia:** React docs: useMemo -- https://react.dev/reference/react/useMemo
+```
+
+</guidelines>
+
+<anti_patterns>
+
+### Anti-padroes (Sugestoes Invalidas)
+
+Estes padroes tornam uma sugestao invalida e devem ser corrigidos antes de incluir no relatorio:
+
+1. **Sugestao sem arquivo concreto**
+   Invalido: "O projeto deveria usar TypeScript"
+   Valido: "src/utils/helpers.js linha 12 -- funcao `parseDate` sem tipagem causa erro silencioso em input invalido"
+
+2. **Problema vago**
+   Invalido: "O codigo pode melhorar"
+   Valido: "Funcao `calculateTotal` (linha 45) usa loop aninhado O(n^2) para lookup que poderia ser O(1) com Map"
+
+3. **Sugestao vaga**
+   Invalido: "Considerar refatorar"
+   Valido: "Extrair logica de validacao das linhas 23-67 para funcao `validateOrder()` -- reduz complexidade ciclomatica de 12 para 4"
+
+4. **Esforco/impacto sem justificativa para G**
+   Invalido: Esforco=G sem explicar por que no campo Sugestao
+   Valido: Esforco=G com "Requer migrar de Moment.js para date-fns em 14 arquivos, incluindo formatacao de datas no backend"
+
+5. **Sugestao duplicada entre dimensoes**
+   Se performance e modernidade encontram o mesmo problema, uma dimensao cria a sugestao e a outra referencia via ID: "Ver PERF-005"
+
+</anti_patterns>