kakaroto-config 1.0.1 → 1.0.2

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 ...
+```

package/config/commands/debug/templates/diagnosis-script.md

@@ -0,0 +1,72 @@
+# Template: Script de Diagnostico
+
+Para bugs Backend/API/Job/Integration, criar `scripts/debug-{descricao}.ts`.
+
+**Exit codes:**
+- 0: Bug NAO presente (comportamento correto)
+- 1: Bug PRESENTE (comportamento incorreto)
+
+---
+
+## Template
+
+```typescript
+#!/usr/bin/env npx tsx
+/**
+ * Diagnostico: {descricao do bug}
+ * Bug: {$ARGUMENTS}
+ * Data: {timestamp}
+ */
+import { config } from 'dotenv';
+config();
+
+async function diagnose(): Promise<boolean> {
+  console.log('='.repeat(60));
+  console.log('DIAGNOSTICO: {nome}');
+  console.log('='.repeat(60));
+  console.log('');
+
+  // 1. Setup
+  console.log('1. Setup...');
+  // [codigo de setup]
+
+  // 2. Reproducao
+  console.log('');
+  console.log('2. Reproduzindo cenario...');
+  // [codigo que reproduz o cenario do bug]
+
+  // 3. Verificacao
+  console.log('');
+  console.log('3. Verificando resultado...');
+  // [verificar se resultado esta correto]
+
+  const resultado = /* valor obtido */;
+  const esperado = /* valor esperado */;
+  const bugPresente = resultado !== esperado;
+
+  // 4. Resultado
+  console.log('');
+  console.log('='.repeat(60));
+  console.log('RESULTADO');
+  console.log('='.repeat(60));
+  console.log('Esperado:', esperado);
+  console.log('Obtido:', resultado);
+  console.log('Bug presente:', bugPresente ? 'SIM' : 'NAO');
+
+  return bugPresente;
+}
+
+diagnose()
+  .then(bugPresente => process.exit(bugPresente ? 1 : 0))
+  .catch(err => {
+    console.error('Erro fatal:', err);
+    process.exit(1);
+  });
+```
+
+---
+
+## Artefatos Alternativos
+
+**Para UI:** screenshot + snapshot do Playwright
+**Para Test:** output do npm test com stack trace

package/config/commands/debug/templates/reproduction-doc.md

@@ -0,0 +1,60 @@
+# Template: Documentacao de Reproducao
+
+Salvar em `.claude/debug/reproduction.md`.
+
+**O output original DEVE ser salvo na integra para comparacao em 04-verify.**
+
+---
+
+## Template
+
+```markdown
+# Reproducao: {descricao curta do bug}
+
+**Data:** {timestamp}
+**Bug:** {$ARGUMENTS}
+
+## Triage
+- Keywords: {lista}
+- Categoria: {categoria}
+
+## Contexto
+- Logs de producao: {sim/nao}
+- Arquivos identificados: {lista}
+
+## Reproducao
+- Playbook: {backend/api/ui/job/integration/test/infra}
+- Artefato: {path do script ou screenshot}
+- Exit code: {0 ou 1}
+
+### Passos Executados
+1. {passo}
+2. {passo}
+
+### Input
+{dados de entrada}
+
+### Output Esperado
+{o que deveria acontecer}
+
+### Output Real (EVIDENCIA) - SALVAR NA INTEGRA
+
+\`\`\`
+{COPIAR OUTPUT COMPLETO DO SCRIPT AQUI}
+{Este output sera comparado em 04-verify}
+\`\`\`
+
+### Exit Code Original
+- **Exit code:** {0 ou 1}
+- **Bug presente:** {SIM ou NAO}
+
+## Observacoes
+{hipoteses formadas durante reproducao}
+```
+
+---
+
+## Nota para 04-verify
+
+O output acima sera comparado com re-execucao do script.
+Se mudar de "Bug presente: SIM" para "NAO", o fix funcionou.

package/config/commands/debug/templates/root-cause-doc.md

@@ -0,0 +1,46 @@
+# Template: Documentacao de Causa Raiz
+
+Criar arquivo `.claude/debug/root-cause.md`.
+
+---
+
+## Template
+
+```markdown
+# Causa Raiz: {descricao curta}
+
+**Data:** {timestamp}
+**Bug:** {referencia a reproduction.md}
+
+## Classificacao do Fluxo
+- [ ] ORIGEM / [ ] TRANSFORMACAO / [ ] USO
+
+## Hipoteses Testadas
+| # | Hipotese | Resultado | Evidencia |
+|---|----------|-----------|-----------|
+| 1 | [causa A] | Refutada | [por que] |
+| 2 | [causa B] | CONFIRMADA | arquivo:linha |
+
+## Causa Raiz
+**Arquivo:** {path}
+**Linha:** {numero}
+**Codigo Atual:**
+\`\`\`typescript
+{codigo problematico}
+\`\`\`
+
+**Problema:** {explicacao clara}
+
+## Fix Proposto
+**Tipo:** CORRECAO DE LOGICA / FILTRO / WORKAROUND
+**Codigo Novo:**
+\`\`\`typescript
+{codigo corrigido}
+\`\`\`
+
+## Validacao
+- [x] Pode ser mudado no codigo
+- [x] Suportada por evidencia
+- [x] Explica todos os sintomas
+- [x] Resolve causa, nao esconde sintoma
+```

package/config/commands/debug/validators/criticality-gate.md

@@ -0,0 +1,40 @@
+# Validator: Criticality Gate
+
+Gate de criticidade - paths criticos requerem aprovacao.
+
+---
+
+## Lista de Paths Criticos
+
+```
+PATHS_CRITICOS:
+- **/auth/**
+- **/payment/**
+- **/migration*/**
+- **/oauth*
+- **/credential*
+- **/secret*
+- api/middleware.ts
+- services/*Service.ts (core services)
+```
+
+---
+
+## Decision Gate
+
+**SE** arquivos afetados ∩ PATHS_CRITICOS **nao vazio**:
+
+1. Documentar fix planejado:
+   - Causa raiz (com evidencia)
+   - Arquivos a modificar
+   - Mudancas propostas
+   - Riscos identificados
+
+2. Chamar `EnterPlanMode`
+   - Escrever plano de fix em `.claude/plans/debug-fix-{timestamp}.md`
+   - User aprova ou rejeita via ExitPlanMode
+
+3. Apos aprovacao: Prosseguir para implementacao
+
+**SENAO** (nao critico):
+Prosseguir direto para implementacao (autonomia total)

package/config/commands/debug/validators/evidence-requirements.md

@@ -0,0 +1,48 @@
+# Validator: Evidence Requirements
+
+Gate de reproducao - criterios de evidencia por categoria.
+
+---
+
+## Criterios de Evidencia por Categoria
+
+| Categoria | Evidencia Minima Requerida |
+|-----------|---------------------------|
+| Backend | Output do script mostrando comportamento incorreto |
+| API | Response body com status code ou mensagem de erro |
+| UI | Screenshot/snapshot mostrando o bug + console errors |
+| Job | Log entry mostrando falha ou comportamento errado |
+| Integration | Erro da API externa ou credencial invalida |
+| Test | Stack trace com linha da assertion que falha |
+| Infra/Deploy | Log de startup mostrando erro ou env var faltando |
+
+---
+
+## Decision Gate
+
+**SE** reproduziu com sucesso (tem evidencia):
+- Documentar em `REPRODUCAO`
+- Prosseguir para persistir reproducao
+
+**SE NAO** reproduziu apos executar playbook:
+- Tentar proximo playbook mais provavel (se categoria incerta)
+- **SE** 3 tentativas falharam:
+  - Usar `AskUserQuestion` para obter mais detalhes
+  - Documentar o que foi tentado
+  - **NAO prosseguir ate reproduzir**
+
+---
+
+## Formato de Documentacao
+
+```
+REPRODUCAO:
+- Categoria: [Backend/API/UI/Job/Integration/Test]
+- Playbook usado: [backend/api/ui/job/integration/test/infra]
+- Passos executados: [lista]
+- Input: [dados de entrada]
+- Output esperado: [o que deveria acontecer]
+- Output real: [o que aconteceu - EVIDENCIA]
+- Artefato: [scripts/debug-X.ts ou screenshot]
+- Reproduzido: SIM/NAO
+```

package/config/commands/debug/validators/fix-permanence.md

@@ -0,0 +1,56 @@
+# Validator: Fix Permanence
+
+Gate de permanencia - fix deve sobreviver a eventos de infra.
+
+---
+
+## Checklist de Sobrevivencia
+
+O fix proposto sobrevive a:
+
+| Evento | Sobrevive? | Justificativa |
+|--------|------------|---------------|
+| Docker container restart | [ ] SIM / [ ] NAO | |
+| VM restart | [ ] SIM / [ ] NAO | |
+| `/deploy` (build + push + reset) | [ ] SIM / [ ] NAO | |
+| `terraform apply` | [ ] SIM / [ ] NAO | |
+| VM destroy/create | [ ] SIM / [ ] NAO | |
+
+---
+
+## Gate de Correcao Manual
+
+**SE** fix envolveu correcao manual de arquivo de config:
+
+| Pergunta | Resposta |
+|----------|----------|
+| Arquivo e gerado por algum processo? | [ ] SIM / [ ] NAO |
+| SE SIM: Processo gerador foi corrigido? | [ ] SIM / [ ] NAO |
+| Fix sobrevive a re-geracao? | [ ] SIM / [ ] NAO |
+
+**SE** qualquer resposta = NAO:
+- Fix e PALIATIVO (sera perdido)
+- **OBRIGATORIO**: Voltar para Investigate
+- ACAO: Read ~/.claude/commands/debug/techniques/flow-tracing.md (Passo 4.1)
+
+---
+
+## Decision Gate
+
+**SE** qualquer item = NAO:
+- O fix e TEMPORARIO (hotfix/paliativo)
+- Documentar: "Este fix sera perdido em [evento]"
+- **OBRIGATORIO**: Implementar fix PERMANENTE que sobreviva a todos os eventos
+
+**SE** todos = SIM:
+- Prosseguir para implementacao
+
+---
+
+## Red Flags
+
+> **NUNCA** declare um bug como "resolvido" se o fix nao sobrevive a `/deploy`.
+>
+> Fix manual na VM e um HOTFIX, nao uma solucao.
+>
+> Corrigir arquivo de config SEM verificar processo gerador = bug retorna no proximo deploy.

package/config/commands/debug/validators/root-cause-validation.md

@@ -0,0 +1,50 @@
+# Validator: Root Cause Validation
+
+Validar causa raiz antes de propor fix.
+
+---
+
+## Checklist Obrigatoria
+
+A causa raiz identificada DEVE passar em TODAS:
+
+- [ ] Algo que voce pode MUDAR no codigo
+- [ ] Suportada por evidencia de codigo (arquivo:linha)
+- [ ] Explica TODOS os sintomas observados na reproducao
+- [ ] **O fix vai RESOLVER o problema, nao apenas ESCONDER?**
+- [ ] **Se um erro legitimo acontecer, ele ainda sera reportado?**
+
+---
+
+## Teste do Devil's Advocate
+
+Antes de prosseguir, responder:
+
+1. **"Em que situacao meu fix pode dar ERRADO?"**
+   Resposta: [descreva cenario]
+
+2. **"Meu fix resolve a CAUSA ou apenas esconde o SINTOMA?"**
+   Resposta: [CAUSA / SINTOMA - se SINTOMA, volte ao Passo 2]
+
+3. **"Se eu adicionar a uma lista de ignore, por que nao posso corrigir a logica?"**
+   Resposta: [justifique ou admita que pode corrigir a logica]
+
+4. **"Meu fix sobrevive a um /deploy? E terraform apply? E VM restart?"**
+   Resposta: [SIM para todos / especificar qual falha]
+
+---
+
+## Categorizacao do Fix Proposto
+
+Classifique seu fix:
+- [ ] **CORRECAO DE LOGICA**: Mudar comportamento incorreto → Preferivel
+- [ ] **FILTRO/IGNORE**: Adicionar a lista de coisas a ignorar → REQUER JUSTIFICATIVA
+- [ ] **WORKAROUND**: Contornar sem resolver → REQUER JUSTIFICATIVA
+
+**SE FILTRO ou WORKAROUND**: Documente por que CORRECAO DE LOGICA nao e possivel.
+
+---
+
+## Decision Gate
+
+**SE** nao validar: voltar a investigacao com nova hipotese via Sequential Thinking.

package/config/commands/debug.md

@@ -10,7 +10,7 @@ ACAO OBRIGATORIA: Read ~/.claude/commands/debug/01-reproduce.md
 Seguir instrucoes. Cada fase aponta para a proxima.
 
 ## Fluxo
-Reproduce → Investigate → Fix → Verify → Commit → Fim (SEM PARADAS)
+Reproduce → Investigate → Fix → Verify → Commit → Evaluate → Fim (SEM PARADAS)
 
 ## Regras
 1. ZERO paradas até o final

package/config/commands/feature/01-interview.md

@@ -1,114 +1,83 @@
 # Fase 1: Interview
 
-## Passo 1: Exploração Autônoma (ANTES de qualquer pergunta)
+## Passo 1: Entender o Request
 
-### 1.1 Carregar Contexto
+Analisar $ARGUMENTS para identificar:
+- Qual feature está sendo solicitada
+- Termos-chave para busca
+- Área provável do codebase (api/, components/, services/)
+
+---
+
+## Passo 2: Buscar Contexto Específico
+
+Baseado no Passo 1, carregar APENAS o necessário:
+
+### 2.1 Memory (se relevante)
 ```
-mcp__memory__search_nodes({ query: "config" })
-mcp__memory__search_nodes({ query: "<termos-da-feature>" })
+mcp__memory__search_nodes({ query: "<termos-específicos-da-feature>" })
 ```
 
-### 1.2 Explorar Codebase
+### 2.2 Codebase (áreas identificadas)
 ```
-Glob: **/*.ts, **/*.tsx
-Read: package.json, schema.prisma (se existir)
-Grep: termos relacionados à feature
+Grep: termos em <área-específica>/
+Read: arquivos diretamente relacionados
 ```
 
-### 1.3 Identificar Patterns
-- Como components similares funcionam
-- Como services são estruturados
-- Como erros são tratados
-- Como loading states funcionam
+**Evitar:** `Glob: **/*.ts` ou buscas genéricas em todo codebase.
 
-**Você DEVE saber (não perguntar):**
-- Estrutura de pastas
-- Schema do banco
-- Libs disponíveis
-- Patterns existentes
+---
+
+## Passo 3: Identificar Patterns (sob demanda)
+
+Após encontrar código relevante, identificar:
+- Como components/services similares funcionam
+- Como erros são tratados nessa área
+- Patterns específicos a seguir
 
 ---
 
-## Passo 2: Reflexão (ANTES de perguntar)
+## Passo 4: Reflexão
 
 Usar `mcp__sequential-thinking__sequentialthinking`:
 
-1. **O que descobri** - Síntese da exploração (patterns, services, schema encontrados)
-2. **O que ainda posso descobrir** - Gaps que consigo preencher explorando mais código
-3. **O que APENAS o user pode responder** - Decisões de produto, preferências de UX
-4. **Tentar descobrir o que falta** - Última tentativa autônoma antes de perguntar
-5. **Formular perguntas mínimas** - Só o essencial que não consegui descobrir
+1. **O que descobri** - Síntese do contexto carregado
+2. **O que ainda posso descobrir** - Gaps que consigo preencher explorando mais
+3. **O que APENAS o user pode responder** - Decisões de produto, preferências UX
+4. **Formular perguntas mínimas** - Só o essencial
 
-`totalThoughts`: 5
+`totalThoughts`: 4
 
 ---
 
-## Passo 3: Perguntas ao User (APENAS decisões de produto)
+## Passo 5: Perguntas ao User (APENAS decisões de produto)
 
 **Usar AskUserQuestion para todas as perguntas.**
 
-### 3.1 Problema e Escopo
-```javascript
-AskUserQuestion({
-  questions: [
-    {
-      question: "Qual problema principal essa feature resolve?",
-      header: "Problema",
-      multiSelect: false,
-      options: [
-        { label: "Eficiência", description: "Processo manual que precisa ser automatizado" },
-        { label: "Funcionalidade", description: "Capacidade que não existe hoje" },
-        { label: "UX", description: "Experiência que precisa melhorar" }
-      ]
-    },
-    {
-      question: "Qual escopo para primeira versão?",
-      header: "Escopo",
-      multiSelect: false,
-      options: [
-        { label: "MVP mínimo", description: "Só o essencial" },
-        { label: "MVP completo", description: "Casos principais cobertos" },
-        { label: "Feature completa", description: "Todos os casos de uso" }
-      ]
-    }
-  ]
-})
-```
+### Perguntas típicas (adaptar ao contexto):
+- **Problema**: Qual problema principal resolve? (Eficiência/Funcionalidade/UX)
+- **Escopo**: MVP mínimo ou feature completa?
+- **Design**: Tem referência ou seguir patterns existentes?
+- **Trade-offs**: Se encontrar 2 approaches, qual preferir?
 
-### 3.2 UX (se aplicável)
+Exemplo de uso:
 ```javascript
 AskUserQuestion({
   questions: [{
-    question: "Há design/mockup de referência?",
-    header: "Design",
-    multiSelect: false,
+    question: "[pergunta específica]",
+    header: "[2-3 palavras]",
     options: [
-      { label: "Sim, tenho", description: "Vou compartilhar" },
-      { label: "Seguir padrão", description: "Usar patterns do app" },
-      { label: "Proponha", description: "Quero sugestão" }
-    ]
-  }]
-})
-```
-
-### 3.3 Trade-offs (apenas se houver decisão com impacto)
-```javascript
-AskUserQuestion({
-  questions: [{
-    question: "Encontrei 2 approaches. Qual prefere?",
-    header: "Approach",
-    multiSelect: false,
-    options: [
-      { label: "Approach A", description: "[trade-off A]" },
-      { label: "Approach B", description: "[trade-off B]" }
-    ]
+      { label: "[opção]", description: "[trade-off]" },
+      { label: "[opção]", description: "[trade-off]" }
+    ],
+    multiSelect: false
   }]
 })
 ```
 
 ---
 
-## Passo 4: Apresentar Descobertas
+## Passo 6: Apresentar Descobertas
 
 Mostrar ao user:
 - Services/patterns encontrados
@@ -118,23 +87,46 @@ Mostrar ao user:
 
 ---
 
-## Passo 5: Checkpoint
+## Passo 7: Persistir Interview
 
-Usar TodoWrite para registrar conclusao da fase:
+### 7.1 Gerar slug
+Primeira palavra do problema + data. Exemplo: `filtro-2026-01-10.md`
 
-```javascript
-TodoWrite({
-  todos: [
-    { content: "Interview: contexto carregado", status: "completed", activeForm: "Loading context" },
-    { content: "Interview: codebase explorado", status: "completed", activeForm: "Exploring codebase" },
-    { content: "Interview: perguntas respondidas", status: "completed", activeForm: "Answering questions" },
-    { content: "Interview: descobertas documentadas", status: "completed", activeForm: "Documenting findings" },
-    { content: "Spec: gerar especificacao", status: "pending", activeForm: "Generating spec" }
-  ]
-})
+### 7.2 Salvar respostas
+```
+Write .claude/interviews/{slug}.md
+Write .claude/interviews/current.md (cópia do conteúdo)
+```
+
+### 7.3 Formato do arquivo
+```markdown
+# Interview: {feature-name}
+
+## Contexto Descoberto
+- Services encontrados: [lista]
+- Patterns identificados: [lista]
+- Código reutilizável: [arquivos:linhas]
+
+## Perguntas e Respostas
+| # | Pergunta | Resposta | Impacto na Implementação |
+|---|----------|----------|--------------------------|
+| 1 | [pergunta] | [resposta] | [como afeta] |
+
+## Decisões Implícitas
+- [decisões inferidas do contexto ou defaults do projeto]
+
+## Termos-chave para Busca
+- [termos que outras fases podem usar para grep/search]
 ```
 
-**Gate:** SE items de Interview nao estao "completed" → Completar antes de prosseguir
+---
+
+## Passo 8: Checkpoint
+
+Usar TodoWrite para registrar items da fase Interview como "completed".
+Adicionar "Spec: gerar especificacao" como "pending".
+
+**Gate:** Todos items de Interview devem estar "completed" E interviews/current.md deve existir.
 
 ---