kakaroto-config 1.0.1 → 1.0.3

package/config/commands/debug/01-reproduce.md

@@ -1,107 +1,107 @@
 # Fase 1: Reproduce
 
-## Passo 1: Carregar Contexto
+Responsabilidade: **ONDE** esta o bug + **COMO** reproduzir + **EVIDENCIA** concreta
 
-```
-mcp__memory__search_nodes({ query: "config" })
-mcp__memory__search_nodes({ query: "<termos-do-bug>" })
-```
+---
 
-Extrair termos relevantes de $ARGUMENTS e buscar bugs similares ja resolvidos.
+## Passo 1: Triage
 
----
+Classificar o bug por keywords em $ARGUMENTS:
 
-## Passo 2: Reproduzir Bug
+| Categoria | Keywords |
+|-----------|----------|
+| Backend/Service | service, funcao, null, undefined, dados, firestore, db, retorna |
+| API/Endpoint | endpoint, API, request, response, 4xx, 5xx, validation, handler |
+| UI/Frontend | UI, componente, renderiza, tela, botao, estado, react, tsx |
+| Job/Cron | job, cron, schedule, nao executou, analytics, executor |
+| Integration | credencial, token, auth, OAuth, secret, API externa |
+| Test | teste, test, falha, assertion, mock, spec |
+| Infra/Deploy | VM, startup, env, terraform, deploy, container, docker, GCP, faltando |
 
-### 2.1 Executar Passos
-Tentar reproduzir com informacoes fornecidas.
+**SE** nenhuma keyword match → Default: **Backend/Service**
 
-### 2.2 Documentar
 ```
-REPRODUCAO:
-- Passos: [...]
-- Input: [...]
-- Output esperado: [...]
-- Output real: [...]
-- Reproduzido: SIM/NAO
+TRIAGE:
+Keywords encontradas: [...]
+Categoria: [Backend/API/UI/Job/Integration/Test/Infra]
 ```
 
 ---
 
-## Passo 3: Verificar Estado Externo (SE web/scraping)
-
-**APENAS SE** o bug envolve: web scraping, Playwright, Puppeteer, seletores, ou interacao com paginas web externas.
-
-### 3.1 Verificar Antes de Assumir
+## Passo 2: Carregar Contexto
 
 ```
-1. mcp__playwright__browser_navigate({ url: "[URL do bug]" })
-2. mcp__playwright__browser_wait_for({ time: 3 })
-3. mcp__playwright__browser_snapshot({})
+mcp__memory__search_nodes({ query: "config" })
+mcp__memory__search_nodes({ query: "<termos-do-bug>" })
 ```
 
-### 3.2 Comparar Estado Atual vs Esperado
+---
 
-- O que o codigo espera encontrar?
-- O que realmente existe na pagina?
-- Quais seletores existem/mudaram?
+## Passo 3: Contexto Rapido
 
-**PROIBIDO:** Assumir que "a pagina mudou" sem verificar.
+### 3.1 Logs de Producao
 
----
+**SE** `.claude/debug-logs.json` existe e `enabled=true`:
+```bash
+{valor de commands.quick}
+```
 
-## Passo 4: Gate de Reproducao
+### 3.2 Exploracao Basica
 
-**SE** reproduziu com sucesso:
-- Prosseguir para Passo 5
+```
+Grep: termos do bug em services/, api/, cron/, components/
+Glob: arquivos com nomes relacionados
+```
 
-**SE NAO** reproduziu:
-- Usar `AskUserQuestion` para obter mais detalhes
-- Documentar o que foi tentado
-- NAO prosseguir ate reproduzir
+```
+LOCALIZACAO:
+Arquivos candidatos: [arquivo1.ts, arquivo2.ts]
+Funcoes suspeitas: [funcao1(), funcao2()]
+```
 
 ---
 
-## Passo 5: Persistir Reproducao
+## Passo 4: Executar Playbook
+
+ACAO: Read ~/.claude/commands/debug/playbooks/{categoria}.md
+
+| Categoria | Playbook |
+|-----------|----------|
+| Backend/Service | backend.md |
+| API/Endpoint | api.md |
+| UI/Frontend | ui.md |
+| Job/Cron | job.md |
+| Integration | integration.md |
+| Test | test.md |
+| Infra/Deploy | infra.md |
 
-Salvar documentacao em `.claude/debug/reproduction.md`:
+---
 
-```markdown
-# Reproducao: [descricao curta do bug]
+## Passo 5: Criar Artefato
 
-**Data:** [timestamp]
-**Bug:** [descricao original de $ARGUMENTS]
+ACAO: Read ~/.claude/commands/debug/templates/diagnosis-script.md
 
-## Passos de Reproducao
-1. [passo executado]
-2. [passo executado]
+---
 
-## Input
-[dados de entrada usados]
+## Passo 6: Gate de Reproducao
 
-## Output Esperado
-[o que deveria acontecer]
+ACAO: Read ~/.claude/commands/debug/validators/evidence-requirements.md
 
-## Output Real
-[o que aconteceu - evidencia do bug]
+---
 
-## Observacoes Iniciais
-[hipoteses formadas durante reproducao]
+## Passo 7: Persistir Reproducao
 
-## Estado Externo (se aplicavel)
-[observacoes do Playwright/browser]
-```
+ACAO: Read ~/.claude/commands/debug/templates/reproduction-doc.md
 
 ---
 
-## Passo 6: Checkpoint
+## Passo 8: Checkpoint
 
 ```javascript
 TodoWrite({
   todos: [
-    { content: "Reproduce: contexto carregado", status: "completed", activeForm: "Loading context" },
-    { content: "Reproduce: bug reproduzido", status: "completed", activeForm: "Reproducing bug" },
-    { content: "Reproduce: reproducao persistida", status: "completed", activeForm: "Persisting reproduction" },
+    { content: "Reproduce: triage + playbook", status: "completed", activeForm: "Bug triaged" },
+    { content: "Reproduce: artefato + evidencia", status: "completed", activeForm: "Evidence collected" },
     { content: "Investigate: analisar causa raiz", status: "pending", activeForm: "Analyzing root cause" }
   ]
 })
@@ -111,8 +111,10 @@ TodoWrite({
 
 ## Output
 
-Bug reproduzido e documentado em `.claude/debug/reproduction.md`.
+Bug reproduzido com evidencia em `.claude/debug/reproduction.md`.
 
 ---
+
 ## PROXIMA FASE
+
 ACAO OBRIGATORIA: Read ~/.claude/commands/debug/02-investigate.md

package/config/commands/debug/02-investigate.md

@@ -1,76 +1,80 @@
 # Fase 2: Investigate
 
-## Passo 0: Context
+Responsabilidade: **POR QUE** o bug acontece + **CAUSA RAIZ**
 
-**SE** continuacao direta de 01-reproduce (mesma sessao):
-  Contexto ja disponivel, prosseguir.
+---
 
-**SE** retomando sessao interrompida:
-```
-Read .claude/debug/reproduction.md
-```
+## Principio
+
+> Fixes corrigem LOGICA, nao filtram SINTOMAS.
+> Antes de propor FILTRO/IGNORE: por que o erro e gerado em primeiro lugar?
+
+---
+
+## Passo 1: Context
+
+**SE** continuacao direta de 01-reproduce: Contexto ja disponivel.
+**SE** retomando sessao: `Read .claude/debug/reproduction.md`
 
 ---
 
-## Passo 1: Explorar Codigo Relacionado
+## Passo 2: Explorar Codigo
 
-### 1.1 Buscar no Codebase
 ```
 Grep: termos do bug
 Glob: arquivos com nomes relacionados
 git log --oneline --grep="fix" -- [arquivos suspeitos]
 ```
 
-### 1.2 Identificar
+Identificar:
 - Arquivos/funcoes envolvidos
 - Como erros sao tratados nesta area
 - Ha validacao que deveria existir?
-- Ha helper existente que resolve?
 
 ---
 
-## Passo 2: 5 Whys (Causa Raiz)
+## Passo 3: Rastreamento de Fluxo
 
-Para cada "Por que?", fornecer EVIDENCIA de codigo:
+**SE** bug envolve dados incorretos (null, undefined, formato invalido):
 
-```
-ANALISE DE CAUSA RAIZ:
+ACAO: Read ~/.claude/commands/debug/techniques/flow-tracing.md
 
-Sintoma: [o que esta acontecendo]
+---
 
-Por que #1: [resposta]
-  Evidencia: [arquivo:linha] - [codigo]
+## Passo 4: Geracao de Hipoteses
 
-Por que #2: [resposta]
-  Evidencia: [arquivo:linha] - [codigo]
+ACAO: Read ~/.claude/commands/debug/techniques/hypothesis-generation.md
 
-Por que #3: [resposta]
-  Evidencia: [arquivo:linha] - [codigo]
+---
 
-CAUSA RAIZ: [declaracao clara]
-```
+## Passo 5: Sequential Thinking
+
+ACAO: Read ~/.claude/commands/debug/techniques/sequential-thinking-config.md
+
+**SE** categoria = Infra/Deploy:
+Consultar secao "Fase: Investigate" em playbooks/infra.md
 
 ---
 
-## Passo 3: Validar Causa Raiz
+## Passo 6: Validar Causa Raiz
 
-A causa raiz deve ser:
-- [ ] Algo que voce pode MUDAR
-- [ ] Suportada por evidencia de codigo
-- [ ] Explica TODOS os sintomas
+ACAO: Read ~/.claude/commands/debug/validators/root-cause-validation.md
 
-**SE** nao validar: voltar ao Passo 2.
+---
+
+## Passo 7: Documentar Causa Raiz
+
+ACAO: Read ~/.claude/commands/debug/templates/root-cause-doc.md
 
 ---
 
-## Passo 4: Checkpoint
+## Passo 8: Checkpoint
 
 ```javascript
 TodoWrite({
   todos: [
     { content: "Reproduce: bug reproduzido", status: "completed", activeForm: "Bug reproduced" },
-    { content: "Investigate: codigo explorado", status: "completed", activeForm: "Code explored" },
-    { content: "Investigate: causa raiz identificada", status: "completed", activeForm: "Root cause identified" },
+    { content: "Investigate: causa raiz validada", status: "completed", activeForm: "Root cause validated" },
     { content: "Fix: implementar correcao", status: "pending", activeForm: "Implementing fix" }
   ]
 })
@@ -80,8 +84,10 @@ TodoWrite({
 
 ## Output
 
-Causa raiz documentada com evidencia.
+Causa raiz documentada em `.claude/debug/root-cause.md`.
 
 ---
+
 ## PROXIMA FASE
+
 ACAO OBRIGATORIA: Read ~/.claude/commands/debug/03-fix.md

package/config/commands/debug/03-fix.md

@@ -1,54 +1,45 @@
 # Fase 3: Fix
 
-## Contexto
-Causa raiz identificada. Implementar fix de forma AUTONOMA.
+Responsabilidade: Implementar fix de forma AUTONOMA.
 
 ---
 
-## Passo 0: Gate de Criticidade
+## Passo 1: Validacao Pre-Fix
 
-### 0.1 Identificar Paths Afetados
+### 1.1 Revisao da Categorizacao
 
-Extrair arquivos da causa raiz documentada na investigacao (fase 02-investigate).
+Na fase Investigate voce categorizou seu fix como:
+- [ ] CORRECAO DE LOGICA → Prossiga
+- [ ] FILTRO/IGNORE → **PARE!** Volte para Investigate
+- [ ] WORKAROUND → **PARE!** Volte para Investigate
 
-### 0.2 Lista de Paths Criticos
+### 1.2 Gate para FILTRO/IGNORE
 
-```
-PATHS_CRITICOS:
-- **/auth/**
-- **/payment/**
-- **/migration*/**
-- **/oauth*
-- **/credential*
-- **/secret*
-- api/middleware.ts
-- services/*Service.ts (core services)
-```
+**SE** fix envolve adicionar a lista de ignore/skip/filter:
+1. Por que o erro esta sendo gerado em primeiro lugar?
+2. Esse padrao pode aparecer em erros legitimos?
+3. Existe forma de corrigir a logica em vez de filtrar?
 
-### 0.3 Decision Gate
+**SE nao conseguir justificar**: Volte para 02-investigate.md
 
-**SE** arquivos afetados ∩ PATHS_CRITICOS **nao vazio**:
+---
 
-1. Documentar fix planejado:
-   - Causa raiz (com evidencia)
-   - Arquivos a modificar
-   - Mudancas propostas
-   - Riscos identificados
+## Passo 2: Gate de Criticidade
 
-2. Chamar `EnterPlanMode`
-   - Escrever plano de fix em `.claude/plans/debug-fix-{timestamp}.md`
-   - User aprova ou rejeita via ExitPlanMode
+ACAO: Read ~/.claude/commands/debug/validators/criticality-gate.md
+
+---
 
-3. Apos aprovacao: Prosseguir para Passo 1
+## Passo 3: Gate de Permanencia
 
-**SENAO** (nao critico):
-Prosseguir direto para Passo 1 (autonomia total)
+ACAO: Read ~/.claude/commands/debug/validators/fix-permanence.md
 
 ---
 
-## Passo 1: Teste de Regressao
+## Passo 4: Teste de Regressao
+
+### 4.1 Criar Teste que Reproduz o Bug
 
-### 1.1 Criar Teste que Reproduz o Bug
 ```typescript
 describe('[contexto do bug]', () => {
   it('should [comportamento esperado]', () => {
@@ -59,7 +50,8 @@ describe('[contexto do bug]', () => {
 })
 ```
 
-### 1.2 Verificar que Teste FALHA
+### 4.2 Verificar que Teste FALHA
+
 ```bash
 npm test -- --testPathPattern="[arquivo]"
 ```
@@ -68,9 +60,8 @@ O teste DEVE falhar antes do fix. Se passar, o teste nao reproduz o bug.
 
 ---
 
-## Passo 2: Implementar Fix
+## Passo 5: Implementar Fix
 
-### 2.1 Fix Minimo
 ```
 FIX:
 Arquivo: [arquivo:linha]
@@ -79,34 +70,28 @@ Depois: [codigo novo]
 Justificativa: [por que resolve a causa raiz]
 ```
 
-### 2.2 Regras
+Regras:
 - APENAS o necessario para resolver a causa raiz
 - NAO refatorar codigo nao relacionado
-- NAO adicionar features
 - Seguir patterns existentes do projeto
 
 ---
 
-## Passo 3: Verificar Fix
+## Passo 6: Verificar Fix
 
-### 3.1 Teste Deve Passar
 ```bash
 npm test -- --testPathPattern="[arquivo]"
 ```
 
-### 3.2 Bug Nao Reproduz
-Executar passos originais. Bug nao deve ocorrer.
-
 ---
 
-## Passo 4: Checkpoint
+## Passo 7: Checkpoint
 
 ```javascript
 TodoWrite({
   todos: [
     { content: "Investigate: causa raiz identificada", status: "completed", activeForm: "Root cause identified" },
-    { content: "Fix: teste de regressao criado", status: "completed", activeForm: "Regression test created" },
-    { content: "Fix: correcao implementada", status: "completed", activeForm: "Fix implemented" },
+    { content: "Fix: teste + correcao implementada", status: "completed", activeForm: "Fix implemented" },
     { content: "Verify: validar quality gates", status: "pending", activeForm: "Validating quality gates" }
   ]
 })
@@ -119,5 +104,7 @@ TodoWrite({
 Fix implementado. Teste de regressao passando.
 
 ---
+
 ## PROXIMA FASE
+
 ACAO OBRIGATORIA: Read ~/.claude/commands/debug/04-verify.md

package/config/commands/debug/04-verify.md

@@ -1,81 +1,155 @@
 # Fase 4: Verify
 
-## Contexto
-Fix implementado. Verificar e finalizar de forma AUTONOMA.
+Responsabilidade: Verificar e finalizar de forma AUTONOMA.
 
 ---
 
 ## Passo 1: Quality Gates
 
-Rodar em sequencia:
 ```bash
-npm test
-npx tsc --noEmit
-npm run build
+npm test && npx tsc --noEmit && npm run build
 ```
 
-**Se falhar:** Corrigir e rodar novamente. Nao prosseguir ate passar.
+**Se falhar:** ACAO: Read ~/.claude/commands/debug/self-healing.md
 
 ---
 
-## Passo 2: Verificacao Final
+## Passo 2: Re-executar Reproducao
 
-- [ ] Testes passam
-- [ ] TypeScript sem erros
-- [ ] Build bem-sucedido
-- [ ] Bug nao reproduz mais
+O script de debug DEVE ser re-executado para confirmar resolucao.
+
+### 2.1 Executar Script
+
+```bash
+npx tsx scripts/debug-{nome-do-bug}.ts
+```
+
+**SE** script nao existe: `ls scripts/debug-*.ts` e executar mais recente.
+
+### 2.2 Comparacao de Output
+
+| Momento | Output |
+|---------|--------|
+| **ANTES** (de `.claude/debug/reproduction.md`) | [output original] |
+| **DEPOIS** | [output atual] |
+
+### 2.3 Decision Gate
+
+**SE** output ainda mostra bug:
+- Fix NAO resolveu a causa raiz
+- ACAO: Read ~/.claude/commands/debug/self-healing.md
+
+**SE** bug resolvido:
+- **SE** categoria = Infra/Deploy: Consultar playbooks/infra.md
+- **SENAO**: Prosseguir para 2.4
+
+### 2.4 Converter Script em Teste de Regressao (se aplicavel)
+
+**SE** script retornou 0 (bug ausente) E arquivo modificado em `cron/`, `services/`, `api/`, `utils/`:
+
+1. Identificar arquivo de teste destino:
+   ```
+   services/foo.ts  → services/foo.test.ts
+   cron/bar.ts      → cron/bar.test.ts (ou criar)
+   ```
+
+2. Converter estrutura do script:
+   ```
+   diagnose()           → describe('regression: {bug}')
+   // 1. Setup          → beforeEach ou inline
+   // 2. Reproducao     → it('should {comportamento correto}', ...)
+   // 3. Verificacao    → expect(...).toBe(...)
+   bugPresente ? 1 : 0  → expect(bugPresente).toBe(false)
+   ```
+
+3. Adicionar ao arquivo de teste:
+   ```typescript
+   describe('regression: {descricao-do-bug}', () => {
+     it('should {comportamento correto apos fix}', async () => {
+       // [codigo adaptado do script de debug]
+       expect(resultado).toBe(esperado);
+     });
+   });
+   ```
+
+4. Validar: `npm test -- --filter="{arquivo}"`
+
+**SE** bug NAO e testavel automaticamente (UI, Infra, Config):
+- Pular conversao, apenas documentar em reproduction.md
+
+**NOTA:** A conversao e recomendada, nao obrigatoria. Usar julgamento.
 
 ---
 
 ## Passo 3: Memory Sync (se bug nao-obvio)
 
-Se o bug foi dificil de encontrar, salvar na memory:
-
 ```javascript
 mcp__memory__create_entities({
   entities: [{
     name: "{prefix}:bug:{nome-descritivo}",
     entityType: "bug",
-    observations: [
-      "Sintoma: [...]",
-      "Causa raiz: [...]",
-      "Solucao: [...]",
-      "Arquivos: [...]"
-    ]
+    observations: ["Sintoma: [...]", "Causa raiz: [...]", "Solucao: [...]"]
   }]
 })
 ```
 
 ---
 
-## Passo 4: Checkpoint
+## Passo 4: Cleanup
+
+### 4.1 Script de Debug
+
+**SE** script foi convertido em teste (2.4):
+```bash
+rm scripts/debug-{nome-do-bug}.ts  # Codigo ja esta no teste
+```
+
+**SE** script NAO foi convertido (bug nao-testavel):
+```bash
+rm scripts/debug-{nome-do-bug}.ts  # Documentacao fica em reproduction.md
+```
+
+### 4.2 Manter Documentacao
+
+NAO deletar:
+- `.claude/debug/reproduction.md`
+- `.claude/debug/root-cause.md`
+
+### 4.3 Verificar Git Status
+
+```bash
+git status
+```
+
+**SE** teste de regressao foi criado: deve aparecer arquivo novo ou modificado
+
+---
+
+## Passo 5: Checkpoint
 
 ```javascript
 TodoWrite({
   todos: [
-    { content: "Reproduce: bug reproduzido", status: "completed", activeForm: "Bug reproduced" },
-    { content: "Investigate: causa raiz identificada", status: "completed", activeForm: "Root cause identified" },
     { content: "Fix: correcao implementada", status: "completed", activeForm: "Fix implemented" },
-    { content: "Verify: quality gates passando", status: "completed", activeForm: "Quality gates passed" },
-    { content: "Commit: commitar e push", status: "pending", activeForm: "Committing changes" }
+    { content: "Verify: quality gates + bug confirmado", status: "completed", activeForm: "Verified" },
+    { content: "Verify: teste de regressao (se aplicavel)", status: "completed", activeForm: "Regression test checked" },
+    { content: "Verify: cleanup feito", status: "completed", activeForm: "Cleanup done" },
+    { content: "Commit: commitar e push", status: "pending", activeForm: "Committing" }
   ]
 })
 ```
 
 ---
 
-## Output
-
-Quality gates passando. Pronto para commit.
-
----
-
 ## Regras Inviolaveis
 
-1. **PROIBIDO** prosseguir com testes falhando
-2. **PROIBIDO** prosseguir com build falhando
-3. **PROIBIDO** perguntar ao user (so reportar no final)
+1. PROIBIDO prosseguir com testes/build falhando
+2. PROIBIDO prosseguir sem re-executar script
+3. PROIBIDO mais de 3 tentativas no self-healing
+4. PROIBIDO deixar script de debug em scripts/ (converter para teste ou deletar)
 
 ---
+
 ## PROXIMA FASE
+
 ACAO OBRIGATORIA: Read ~/.claude/commands/debug/05-commit.md