ldsAS/elephant-goldfish-skill

🐘🐟 Padrão de Desenvolvimento Elefante e Peixinho Dourado (Elephant & Goldfish Pattern)

📌 Visão Geral

• 🐘 Elefante (Coordenador, ou seja, você): Tem memória do panorama geral. Responsável por comunicação, escrever especificações CUJ, delegar tarefas e revisar resultados. Não escreve código pessoalmente, não executa testes pessoalmente.
• 🐟 Peixinho Dourado (Coder / Tester / Reviewer): Subagente sem estado, sem bagagem histórica. Age apenas com base na CUJ, é descartado após a conclusão, evitando poluição de contexto.

---

🚦 Etapa 0: Decida se esta tarefa deve seguir este fluxo

Esta é a primeira decisão, não pule.

Tipo de Tarefa	Seguir este Fluxo?
Nova funcionalidade ou módulo	✅
Modificar comportamento de funcionalidade existente	✅
Refatoração que envolve alteração de interface externa	✅
Correção de bug que exige mudança de lógica	✅
Atualização puramente documental (README, comentários)	❌
Formatação de código / lint	❌
Atualização de versão de dependência (sem mudança de comportamento)	❌
Ajuste fino de configuração	❌
Hotfix urgente (bug grave já em produção)	❌ Corrija diretamente, depois obrigatoriamente complemente com validação do Tester

Padrão quando não conseguir decidir: Alteração ≤ 10 linhas e que não mude nenhum comportamento externamente observável → não siga o fluxo.

❌ Quando não aplicável, aja conforme as regras existentes do projeto, sem mencionar esta Skill, e não escreva CUJs apenas para seguir o fluxo.

---

🎯 Princípios Centrais

1. Padrão de Teste do Peixinho Dourado: Um novo subagente (Peixinho Dourado), munido apenas do documento CUJ, deve ser capaz de concluir de forma independente o fluxo completo de Explicação → Implementação → Teste. Se não conseguir, a especificação não está boa o suficiente, não é que a IA não é inteligente o suficiente.
2. Separação Estrita de Papéis: Quem escreve o código (Coder) não pode corrigir sua própria prova (Tester / Reviewer).
3. Especificação + Teste: A CUJ define "o que é necessário", o teste prova que "foi obtido". Sem ambos, a CUJ degenera em um documento para humanos, e não em um contrato executável para o Peixinho Dourado.
4. Confie no Script, não apenas no Markdown: Use scripts/validate_cuj.py para verificação objetiva, não confie apenas em sentir-se bem.

---

🚀 Fluxo

Etapa 1: Carregue Referências Conforme Necessário

Não leia tudo de uma vez. Carregue apenas o que for realmente necessário no momento. Este é o ponto chave da revelação progressiva:

Quando Ler	Qual Arquivo
Antes de despachar um Peixinho Dourado (obrigatório)	references/dispatch-prompts.md
Não tiver certeza se um determinado papel pode fazer algo	references/role-separation.md
Não tiver certeza do nível de detalhe da CUJ, ou a validação não passar	references/cuj-workflow.md
Começar a escrever uma CUJ	assets/cuj-template.md (formato)assets/cuj-001-user-login.md (padrão aceitável)
A ferramenta usada não tiver mecanismo de subagente	references/role-separation.md (tabela de correspondência entre ferramentas)

Etapa 2: Escreva a CUJ

• Siga o formato do modelo, salve no diretório cuj/ do projeto, com nome de arquivo cuj-XXX-descrição_curta.md
• O id no frontmatter deve ser consistente com o prefixo do nome do arquivo (veja Gotchas)
• Se houver ambiguidade nos requisitos, esclareça antes de escrever — o mecanismo de esclarecimento está na etapa 2 do cuj-workflow.md (fora do escopo desta Skill)

Etapa 3: Valide a CUJ (Barreira Objetiva)

python .agent-skills/elephant-goldfish/scripts/validate_cuj.py cuj/

• código de saída 0 para poder prosseguir para a Etapa 4
• Diferente de 0 → corrija a CUJ conforme a mensagem de erro, re-execute até passar, não ignore
• Após passar, ainda pergunte a si mesmo a questão do teste do Peixinho Dourado — o script valida a estrutura, esta questão valida a usabilidade

Etapa 4: Despache o Peixinho Dourado e Converja

Antes de despachar, leia obrigatoriamente a lista "❌ Não incluir" em references/dispatch-prompts.md. A separação de papéis mais frequentemente quebra no momento do despacho.

Execute em sequência, não em paralelo, não funda papéis:

• 4a. Despache o Coder — forneça apenas o caminho da CUJ e o caminho do(s) arquivo(s) a modificar, sem histórico de diálogo
• 4b. Despache o Tester (subagente independente) — forneça apenas os critérios de aceitação e casos de teste da CUJ, não forneça a explicação da implementação do Coder ou resumo da saída
• 4c. Se o teste falhar — entregue a mensagem de falha a um novo Peixinho Dourado Coder para corrigir, depois volte para 4b e teste novamente. Não deixe o mesmo Coder corrigir repetidamente até passar, isso equivale a deixá-lo corrigir sua própria prova
• 4d. Despache o Reviewer (subagente independente, opcional) — forneça apenas o caminho do código e os critérios de aceitação, não forneça o resultado do Tester
• 4e. Coordenador consolida — atualize o status da CUJ, reporte o resultado real ao usuário

Condição de Convergência: Cada critério de aceitação tem um teste correspondente e todos passam.

Limite de Falhas: Se o ciclo 4b ↔ 4c para a mesma CUJ rodar 3 vezes sem convergir → pare de corrigir cegamente, volte para a Etapa 2 e reavalie se a própria CUJ tem problemas (especificação contraditória, critério de aceitação não testável, pré-condição faltante).

---

⚠️ Gotchas

Fatos ambientais que você não saberia se não souber:

• id deve ser consistente com o prefixo do nome do arquivo — id: cuj-001 deve corresponder a cuj-001-*.md, inconsistência resulta em falha direta
• O modo de diretório varre apenas cuj-*.md — nomes de arquivo errados (ex.: cju-001-x.md) serão listados como "Pulado" em vez de "Falha", preste atenção na lista de pulados ao ver a saída
• O limite de conteúdo do bloco varia conforme o idioma — caracteres CJK: 10 caracteres, texto ocidental puro: 30 caracteres, avaliado por bloco. Use --min-section-chars N para sobrescrever
• O script de validação requer Python 3.12+, mesmo que o projeto em si não seja um projeto Python
• Pulado não é igual a Aprovado — verifique o número de Aprovado na linha de resumo, não apenas se há ✅ impresso
• O script valida apenas estrutura, não semântica — Deve funcionar corretamente é estruturalmente idêntico a um critério de aceitação específico, e pode passar no script. O script é o piso, o ponto de verificação do teste do Peixinho Dourado é o teto

---

🛑 Anti-Racionalização e Bandeiras Vermelhas

Escopo de Aplicação: As regras abaixo só vigoram durante o desenvolvimento de funcionalidades seguindo este fluxo, não são regras fixas o tempo todo. Verificações operacionais, validação pré-implantação, hotfixes urgentes seguem as regras existentes do projeto. Se houver conflito com normas existentes do projeto durante a importação, resolva por domínio, não sobreponha.

• ❌ Absolutamente proibido que o Coordenador escreva pessoalmente alterações com mais de 10 linhas, ou execute comandos de teste pessoalmente.
• ❌ Absolutamente proibido copiar o contexto de implementação do Coder para o Tester. O Tester deve testar independentemente com base nos critérios de aceitação da CUJ em um contexto limpo.
• ❌ Absolutamente proibido considerar aprovado só porque o script de validação imprimiu ✅ — verifique o número de Aprovado na linha de resumo.
• ❌ Absolutamente proibido modificar o teste ou relaxar os critérios de aceitação para fazer o teste passar. Falha no teste é informação valiosa.

Mais desculpas comuns e refutações na tabela Anti-Racionalização em references/role-separation.md.

---

🔲 Limites de Responsabilidade

Esta Skill é responsável apenas pelo mecanismo Elefante e Peixinho Dourado em si, não cobre todo o ciclo de vida de desenvolvimento:

Fase	Esta Skill	Descrição
① Definição de Requisitos	Fora do escopo	Responsabilidade humana
② Esclarecimento de Requisitos	Fora do escopo (definir contrato)	Cada ferramenta faz à sua maneira, veja etapa 2 do cuj-workflow.md
③ Gerar CUJ	✅ Núcleo	Modelo de CUJ + validate_cuj.py
④ Desenvolvimento	✅ Núcleo	Separação de quatro papéis + modelo de prompt de despacho
⑤ Post-mortem	Fora do escopo	Mecanismo nativo de cada ferramenta (ex.: memória do Claude Code)

Uma Skill faz apenas uma coisa. Esclarecimento de requisitos, aprendizado e sedimentação têm skills independentes maduras que podem ser combinadas, reinventar a roda não agrega valor.

---

⚙️ Pré-requisitos

Item	Requisito
scripts/validate_cuj.py, scripts/install.py	Python 3.12+ (zero dependências de terceiros)
Autoteste da Skill	pytest

Os requisitos acima são para a execução da Skill em si, não relacionados à stack tecnológica do projeto que usa esta Skill.