kakaroto-config 1.0.0 → 1.0.2

package/config/commands/debug/06-evaluate.md

@@ -0,0 +1,137 @@
+# Fase 6: Auto-Avaliacao
+
+## Contexto
+Fix commitado. Avaliar workflow de debug e propor melhorias ao config.
+
+---
+
+## Passo 1: Coletar Metricas
+
+```bash
+git diff --stat HEAD~1
+git log -1 --format="%s"
+```
+
+Ler (se existirem):
+- .claude/debug/reproduction.md (como bug foi reproduzido)
+- Arquivos modificados pelo fix
+
+Coletar:
+- Arquivos modificados
+- Linhas adicionadas/removidas
+- Testes de regressao criados
+
+---
+
+## Passo 2: Sequential Thinking #1 - DIAGNOSTICO
+
+Usar mcp__sequential-thinking__sequentialthinking para:
+
+**Objetivo:** Identificar problemas no processo de debug
+
+### 2.1 Avaliar Criterios (0-100%)
+
+| Criterio | Peso | Como Medir |
+|----------|------|------------|
+| Reproducao | 25% | Bug foi reproduzido de forma confiavel? |
+| Root Cause | 25% | 5 Whys chegou na causa raiz real? |
+| Fix Minimal | 20% | Fix foi minimo e cirurgico? Sem over-engineering? |
+| Regressao | 15% | Teste de regressao foi criado? |
+| Permanencia | 10% | Fix sobrevive restart/deploy? |
+| Autonomia | 5% | Quantas perguntas ao user? (ideal: <=2) |
+
+### 2.2 Para Criterios < 80%: Aplicar 5 Whys
+
+1. Por que o score foi baixo?
+2. Qual foi a causa raiz do problema no processo?
+3. O que poderia ter prevenido?
+4. Que informacao/regra faltou no skill?
+5. Onde essa informacao deveria estar?
+
+**Output esperado:** Lista de {problema, causa_raiz, local_ideal}
+
+---
+
+## Passo 3: Sequential Thinking #2 - SINTESE
+
+Usar mcp__sequential-thinking__sequentialthinking novamente:
+
+**Objetivo:** Transformar diagnosticos em mudancas acionaveis
+
+Para cada problema identificado no Passo 2:
+
+1. **Tipo de mudanca?**
+   - Config: Regra no CLAUDE.md
+   - Skill: Gate/validacao em fase de debug
+   - Playbook: Adicionar ao playbook de categoria
+
+2. **Qual arquivo editar?**
+   - ~/.claude/CLAUDE.md
+   - ~/.claude/commands/debug/*.md
+
+3. **Diff exato da mudanca?**
+   - Escrever o texto exato a adicionar
+
+4. **Efeitos colaterais?**
+   - Vai afetar outros tipos de bug?
+   - Pode causar falsos positivos?
+
+5. **Prioridade?**
+   - Alta: Bug similar pode acontecer novamente
+   - Media: Melhoria de processo
+   - Baixa: Nice-to-have
+
+**Output esperado:** Lista de {tipo, arquivo, diff_sugerido, prioridade}
+
+---
+
+## Passo 4: Propor Melhorias ao Usuario
+
+Para cada melhoria identificada (MAXIMO 3 por execucao):
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Detectei: {problema no processo}. Causa: {causa_raiz}. Sugiro adicionar em {arquivo}: '{diff}'. Aplicar?",
+    header: "Melhoria",
+    options: [
+      { label: "Aplicar", description: "Editar {arquivo} com a mudanca sugerida" },
+      { label: "Ignorar", description: "Pular desta vez, pode sugerir novamente" },
+      { label: "Nunca sugerir", description: "Adicionar excecao permanente" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### Acoes por Resposta:
+- **Aplicar:** Usar Edit tool para modificar arquivo
+- **Ignorar:** Prosseguir sem acao
+- **Nunca sugerir:** Adicionar em ~/.claude/evaluation-exceptions.json
+
+---
+
+## Passo 5: Finalizar
+
+Reportar ao user:
+
+```
+## Avaliacao do Workflow de Debug
+
+**Score Final:** X% (Reproducao: X%, Root Cause: X%, Fix: X%, Regressao: X%, Permanencia: X%, Autonomia: X%)
+
+**Melhorias Aplicadas:** N
+- [lista de mudancas aplicadas]
+
+**Workflow /debug concluido.**
+```
+
+---
+
+## Regras Inviolaveis
+
+1. **SEMPRE** executar apos commit bem-sucedido
+2. **NUNCA** aplicar mudanca sem aprovacao explicita do user
+3. **MAXIMO** 3 sugestoes por execucao (evitar decision fatigue)
+4. **PRIORIZAR** problemas de alta prioridade primeiro
+5. **NAO** sugerir mudancas se score >= 90% em todos criterios

package/config/commands/debug/playbooks/api.md

@@ -0,0 +1,21 @@
+# Playbook: API/Endpoint
+
+## Passos
+
+1. **Identificar** handler em `api/handlers/` (ja feito em exploracao basica)
+
+2. **Subir servidor** em background:
+   ```bash
+   npm run dev &
+   ```
+
+3. **Request** com inputs do bug:
+   ```bash
+   curl -X POST http://localhost:{port}/api/{endpoint} \
+     -H "Content-Type: application/json" \
+     -d '{"input": "valor"}'
+   ```
+
+4. **Capturar** response completa (status, body)
+
+5. **Evidencia**: Response mostrando erro ou comportamento incorreto

package/config/commands/debug/playbooks/backend.md

@@ -0,0 +1,19 @@
+# Playbook: Backend/Service
+
+## Passos
+
+1. **Identificar** service/funcao via Grep (ja feito em exploracao basica)
+
+2. **Criar script** `scripts/debug-{descricao}.ts`:
+   ```typescript
+   #!/usr/bin/env npx tsx
+   import { config } from 'dotenv';
+   config();
+   // Import do service
+   // Chamada com inputs do bug
+   // console.log do resultado
+   ```
+
+3. **Executar**: `npx tsx scripts/debug-{descricao}.ts`
+
+4. **Evidencia**: Output mostrando comportamento incorreto

package/config/commands/debug/playbooks/infra.md

@@ -0,0 +1,130 @@
+# Playbook: Infra/Deploy
+
+## Fase: Reproduce
+
+### Passos
+
+1. **Ler arquivos de deploy ANTES de qualquer investigacao**:
+   ```
+   Read terraform/deploy.sh
+   Read terraform/startup-script.sh (ou equivalente)
+   Read terraform/main.tf (locals e env vars)
+   Read terraform/modules/compute-instance/main.tf (lifecycle rules)
+   ```
+
+2. **Mapear ciclo de vida**:
+   - Como a VM inicia?
+   - Como env vars chegam no container?
+   - O que acontece em `/deploy`?
+   - O que acontece em `terraform apply`?
+
+3. **Verificar logs da VM**:
+   ```bash
+   gcloud compute ssh {instance} --command="sudo journalctl -u google-startup-scripts -n 100"
+   ```
+
+4. **Verificar container**:
+   ```bash
+   gcloud compute ssh {instance} --command="sudo docker logs social-medias --tail 50"
+   ```
+
+5. **Evidencia**: Log mostrando erro de startup ou env var faltando
+
+---
+
+## Fase: Investigate
+
+### Mapeamento de Ciclo de Vida
+
+#### Diagrama de Fluxo
+
+```
+CICLO DE VIDA DO BUG:
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  terraform      │ --> │  startup script  │ --> │  container      │
+│  (define vars)  │     │  (aplica vars)   │     │  (usa vars)     │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+         │                       │                       │
+         v                       v                       v
+   Quando muda?            Quando executa?         Quando reinicia?
+   [resposta]              [resposta]              [resposta]
+```
+
+#### Perguntas Obrigatorias
+
+1. **Onde o valor e definido?** (terraform, env, secret, hardcoded)
+2. **Como o valor chega no destino?** (startup script, SCP, mount, API)
+3. **O que dispara atualizacao?** (apply, deploy, restart, nada)
+4. **Ha cache/ignore que bloqueia?** (ignore_changes, cache, stale)
+
+---
+
+## Fase: Verify
+
+### Simulacao de Deploy
+
+```bash
+# Simular o que /deploy faria (sem executar de verdade)
+cd terraform && ./deploy.sh update --dry-run
+
+# OU se nao houver dry-run, verificar manualmente:
+# 1. O que muda no startup script?
+# 2. O que muda no container?
+# 3. Env vars estao corretas?
+```
+
+### Teste de Permanencia
+
+Executar UM dos seguintes (do menos ao mais destrutivo):
+
+1. **Container restart** (rapido, sem downtime):
+   ```bash
+   gcloud compute ssh {instance} --command="sudo docker restart social-medias"
+   # Verificar se bug nao retorna
+   ```
+
+2. **VM restart** (1-2 min downtime):
+   ```bash
+   gcloud compute instances reset {instance} --zone={zone}
+   # Aguardar startup, verificar se bug nao retorna
+   ```
+
+3. **Deploy completo** (se mudancas em terraform):
+   ```bash
+   ./deploy.sh update
+   # Verificar se bug nao retorna
+   ```
+
+### Criterio de Sucesso
+
+- [ ] Fix aplicado persiste apos restart escolhido
+- [ ] Logs nao mostram o erro original
+- [ ] Funcionalidade afetada opera normalmente
+
+---
+
+## Armadilhas de Portabilidade
+
+Scripts podem ter comportamento diferente entre macOS e Linux.
+
+### Padroes Problematicos (BSD vs GNU)
+
+| GNU | BSD/POSIX | Afeta |
+|-----|-----------|-------|
+| `\s` | `[[:space:]]` | sed, grep |
+| `\d` | `[0-9]` | sed, grep |
+| `sed -i ''` (macOS) | `sed -i` (Linux) | in-place |
+
+### Checklist de Portabilidade
+
+SE bug envolve script executado em macOS:
+- [ ] Scripts usam POSIX character classes?
+- [ ] Regex funciona em GNU e BSD?
+
+### Diagnostico
+
+```bash
+# Testar regex
+echo "key  = \"value\"" | sed 's/.*=\s*"\(.*\)"/\1/'
+# Se retornar linha inteira: BSD nao entendeu \s
+```

package/config/commands/debug/playbooks/integration.md

@@ -0,0 +1,16 @@
+# Playbook: Integration
+
+## Passos
+
+1. **Verificar credentials**:
+   ```typescript
+   import { getSecret } from '../services/secretManagerService';
+   const token = await getSecret(accountSlug, '{type}');
+   console.log('Token existe:', !!token);
+   ```
+
+2. **Testar autenticacao** direta com API externa
+
+3. **Verificar** token expiry, quota, rate limit
+
+4. **Evidencia**: Erro da API externa ou credencial invalida/expirada

package/config/commands/debug/playbooks/job.md

@@ -0,0 +1,19 @@
+# Playbook: Job/Cron
+
+## Passos
+
+1. **Verificar config** no Firestore:
+   ```typescript
+   // Query job_configs para ver schedule
+   // Query analytics_job_executions para ver ultima execucao
+   ```
+
+2. **Criar script** ou usar existente:
+   ```bash
+   npx tsx scripts/run-{job-name}.ts
+   ```
+   **OU** criar `scripts/debug-{job}.ts` se nao existir
+
+3. **SE** bug em producao: buscar logs via `.claude/debug-logs.json`
+
+4. **Evidencia**: Logs ou output mostrando falha/comportamento incorreto

package/config/commands/debug/playbooks/test.md

@@ -0,0 +1,14 @@
+# Playbook: Test
+
+## Passos
+
+1. **Rodar teste isolado**:
+   ```bash
+   npm test -- --testPathPattern="{arquivo}"
+   ```
+
+2. **Identificar** assertion que falha no output
+
+3. **SE** necessario: adicionar console.logs temporarios
+
+4. **Evidencia**: Stack trace com linha da assertion

package/config/commands/debug/playbooks/ui.md

@@ -0,0 +1,24 @@
+# Playbook: UI/Frontend
+
+## Passos
+
+1. **Identificar** componente (ja feito em exploracao basica)
+
+2. **Subir dev server** em background:
+   ```bash
+   npm run dev &
+   ```
+
+3. **Navegar** ate pagina/componente:
+   ```
+   mcp__playwright__browser_navigate({ url: "http://localhost:{port}/{path}" })
+   mcp__playwright__browser_wait_for({ time: 3 })
+   ```
+
+4. **Capturar estado**:
+   ```
+   mcp__playwright__browser_snapshot({})
+   mcp__playwright__browser_console_messages({ level: "error" })
+   ```
+
+5. **Evidencia**: Snapshot mostrando bug + console errors (se houver)

package/config/commands/debug/self-healing.md

@@ -0,0 +1,99 @@
+# Self-Healing Loop
+
+## Contexto
+Ativado quando quality gates falham OU bug ainda reproduz OU fix nao e permanente.
+
+---
+
+## Passo 1: Controle de Tentativas
+
+```
+TENTATIVA_ATUAL: {1/2/3}
+```
+
+**SE** tentativa > 3:
+- PARAR imediatamente
+- Reportar ao usuario com analise completa
+- Documentar o que foi tentado e por que falhou
+- NAO continuar autonomamente
+
+---
+
+## Passo 2: Analise de Falha (Sequential Thinking)
+
+Antes de tentar corrigir, ENTENDER por que falhou:
+
+```javascript
+mcp__sequential-thinking__sequentialthinking({
+  thought: "Analisando falha da verificacao...",
+  nextThoughtNeeded: true,
+  thoughtNumber: 1,
+  totalThoughts: 5
+})
+```
+
+Thoughts obrigatorios:
+
+1. **"O que meu fix mudou exatamente?"**
+   - Listar arquivos e linhas modificados
+
+2. **"O que a falha esta me dizendo?"**
+   - Se teste: qual assertion falhou?
+   - Se build: qual erro de compilacao?
+   - Se reproducao: qual sintoma persiste?
+
+3. **"Minha causa raiz estava correta?"**
+   - Revisitar `.claude/debug/root-cause.md`
+   - A evidencia ainda se sustenta?
+
+4. **"O que eu perdi na analise?"**
+   - Ha outro caminho de codigo afetado?
+   - Ha efeito colateral nao considerado?
+
+5. **"Qual a proxima acao?"**
+   - Determinar para onde voltar
+
+---
+
+## Passo 3: Decision Gate
+
+Baseado na analise, escolher UMA opcao:
+
+| Situacao | Acao |
+|----------|------|
+| Fix incompleto (faltou parte) | Voltar para 03-fix, completar |
+| Causa raiz parcial (faltou profundidade) | Voltar para 02-investigate Passo 5 |
+| Causa raiz errada (hipotese refutada) | Voltar para 02-investigate Passo 4 |
+| Reproducao insuficiente | Voltar para 01-reproduce |
+
+---
+
+## Passo 4: Documentar Tentativa
+
+Adicionar em `.claude/debug/attempts.md`:
+
+```markdown
+## Tentativa {N}
+
+**Data:** {timestamp}
+**Falha em:** Quality Gate / Reproducao / Permanencia
+
+**O que foi tentado:**
+{descricao do fix}
+
+**Por que falhou:**
+{analise via Sequential Thinking}
+
+**Proxima acao:**
+{para onde voltar e por que}
+```
+
+---
+
+## Passo 5: Incrementar e Continuar
+
+```
+TENTATIVA_ATUAL += 1
+```
+
+Executar a acao definida no Decision Gate.

package/config/commands/debug/techniques/flow-tracing.md

@@ -0,0 +1,75 @@
+# Tecnica: Rastreamento de Fluxo
+
+Para bugs que envolvem **dados incorretos** (null, undefined, formato invalido, valor inesperado).
+
+---
+
+## Passo 1: Identificar Valor Problematico
+
+- Qual valor esta errado?
+- Onde ele CAUSA o erro? (arquivo:linha)
+
+---
+
+## Passo 2: Rastrear para Tras (Backward Tracing)
+
+Seguir a call chain de volta ate a ORIGEM:
+
+1. **ONDE e usado?** (ponto do erro) → arquivo:linha
+2. **QUEM chama essa funcao?** → `Grep: "nomeDaFuncao("`
+3. **DE ONDE vem o parametro?** → Subir na call chain
+4. **ONDE o valor e definido/calculado?** → Continuar ate achar a ORIGEM
+
+---
+
+## Passo 3: Diagrama de Fluxo
+
+Documentar o caminho completo:
+
+```
+FLUXO DO VALOR:
+[ORIGEM]      →   [transform 1]   →   [transform 2]   →   [USO/ERRO]
+arquivo1:42   →   arquivo2:108    →   arquivo3:55     →   arquivo4:23
+   |                  |                   |                   |
+   v                  v                   v                   v
+ [valor]          [operacao]          [operacao]          [erro]
+```
+
+---
+
+## Passo 4: Classificacao do Bug
+
+O bug esta em qual parte do fluxo?
+
+- [ ] **ORIGEM**: Valor ja nasce errado (ex: input invalido, query errada)
+- [ ] **TRANSFORMACAO**: Valor e corrompido no caminho (ex: parsing, conversao)
+- [ ] **USO**: Valor correto usado incorretamente (ex: logica errada, condicao invertida)
+
+**IMPORTANTE**: O fix deve ser aplicado onde o problema COMECA, nao onde ele APARECE.
+
+---
+
+## Passo 4.1: SE Origem em Arquivo de Config Gerado
+
+**SE** valor incorreto vem de arquivo de config (.env, .json, .yaml):
+
+1. **O arquivo e GERADO ou EDITADO manualmente?**
+   - `Grep: ">.env" ou "generate_" ou "create.*config"`
+
+2. **SE GERADO**: Rastrear processo gerador
+   - QUAL script gera o arquivo?
+   - ONDE no script o valor e definido?
+
+3. **Diagrama Estendido**:
+   ```
+   [PROCESSO]  →  [CONFIG]  →  [APP]
+   deploy.sh   →  .env      →  app.ts
+   ```
+
+4. **Classificacao**:
+   - [ ] ORIGEM EM PROCESSO: Script gera valor errado
+   - [ ] ORIGEM EM TEMPLATE: Template tem erro
+   - [ ] TRANSFORMACAO: Script corrompe durante geracao
+
+**IMPORTANTE**: Corrigir arquivo manualmente e PALIATIVO.
+Fix DEVE corrigir o PROCESSO GERADOR.

package/config/commands/debug/techniques/hypothesis-generation.md

@@ -0,0 +1,30 @@
+# Tecnica: Geracao de Hipoteses
+
+Antes de investigar profundamente, listar MULTIPLAS causas possiveis.
+
+---
+
+## Passo 1: Brainstorm (minimo 3 hipoteses)
+
+| # | Hipotese | Probabilidade | Evidencia Inicial |
+|---|----------|---------------|-------------------|
+| 1 | [causa A] | Alta/Media/Baixa | [o que sugere isso] |
+| 2 | [causa B] | Alta/Media/Baixa | [o que sugere isso] |
+| 3 | [causa C] | Alta/Media/Baixa | [o que sugere isso] |
+
+---
+
+## Passo 2: Ranking
+
+Ordenar hipoteses por:
+1. **Evidencia existente** (logs, reproducao, erros)
+2. **Frequencia historica** (bugs similares ja resolvidos)
+3. **Simplicidade** (Navalha de Occam)
+
+---
+
+## Passo 3: Estrategia de Exploracao
+
+- Comecar pela hipotese #1 no Sequential Thinking
+- SE refutada: usar `branchFromThought` para explorar #2
+- Registrar hipoteses descartadas e POR QUE (evita repetir)

package/config/commands/debug/techniques/sequential-thinking-config.md

@@ -0,0 +1,79 @@
+# Tecnica: Sequential Thinking para Causa Raiz
+
+**OBRIGATORIO**: Usar `mcp__sequential-thinking__sequentialthinking` para analise profunda.
+
+---
+
+## Configuracao Inicial
+
+```javascript
+mcp__sequential-thinking__sequentialthinking({
+  thought: "[hipotese inicial baseada em evidencias]",
+  nextThoughtNeeded: true,
+  thoughtNumber: 1,
+  totalThoughts: 8  // MINIMO 8 thoughts
+})
+```
+
+---
+
+## Regras para Cada Thought
+
+Cada thought DEVE conter:
+
+1. **Hipotese especifica**: "Acredito que o bug acontece porque..."
+2. **Busca de evidencia**: Usar Grep/Read para encontrar arquivo:linha
+3. **Avaliacao**: A evidencia suporta ou refuta a hipotese?
+4. **Proxima acao**:
+   - SE suporta: Ir mais fundo ("Por que isso acontece?")
+   - SE refuta: Marcar `isRevision: true` e tentar alternativa
+
+---
+
+## Parametros Especiais
+
+| Parametro | Quando Usar |
+|-----------|-------------|
+| `isRevision: true` | Quando descartando hipotese anterior |
+| `revisesThought: N` | Indicar qual thought esta sendo revisado |
+| `branchFromThought: N` | Quando explorando caminho alternativo |
+| `branchId: "hipotese-2"` | Identificar o branch atual |
+| `needsMoreThoughts: true` | Se precisa ir mais fundo |
+
+---
+
+## Criterios de Parada
+
+Somente definir `nextThoughtNeeded: false` quando:
+
+- [ ] Chegou em algo que PODE SER MUDADO no codigo
+- [ ] Tem EVIDENCIA concreta (arquivo:linha + codigo)
+- [ ] Nao ha mais "por que?" logico para perguntar
+- [ ] A causa identificada explica TODOS os sintomas
+
+---
+
+## Exemplo de Fluxo
+
+```
+Thought 1: "Hipotese: erro em validateInput()"
+  → Grep encontra validacao em services/videoService.ts:45
+  → Evidencia: funcao nao valida campo X
+
+Thought 2: "Por que nao valida campo X?"
+  → Read services/videoService.ts
+  → Evidencia: schema Zod nao inclui X (linha 12)
+
+Thought 3: "Por que schema nao inclui X?"
+  → git log mostra: adicionado em commit abc123
+  → Evidencia: campo X e novo, schema desatualizado
+
+Thought 4 (isRevision=true): "Mas wait, X deveria ser opcional..."
+  → Re-analisando: o problema e que X e required no destino
+
+Thought 5: "Onde X e required?"
+  → Grep encontra em api/handlers/upload.ts:78
+  → Evidencia: handler espera X mas nao recebe
+
+... continua ate causa raiz confirmada ...
+```