aTeering/skills

Engenheiro

Sintetize a descoberta em dois artefatos duráveis: uma especificação que /implement pode executar e ADRs para decisões que valem a pena lembrar.

Entrada: $ARGUMENTS.

Zero suposições silenciosas. Cada escolha de design é feita pelo usuário ou listada como suposição. Isso inclui escolhas que parecem pequenas demais para perguntar (biblioteca, formato de erro, nomenclatura, padrões, limites), o que você infere da base de código e suas próprias recomendações. Mantenha um Livro de Suposições (✅ confirmado pelo usuário · ❓ não confirmado · ❌ rejeitado) durante todo o processo e nunca escreva uma escolha não confirmada em uma especificação ou ADR como decisão.

Processo

1. Refinar. Se ainda não houver um Brief Refinado nesta sessão, execute o processo /refine primeiro (questionamento → critérios de aceitação). Não prossiga com perguntas em aberto que bloqueiem o design. Se um brief existir, carregue suas suposições ❓ para o seu livro; resolva-as antes de projetar qualquer coisa que dependa delas.
2. Modelar. Execute o processo /domain-modelling para quaisquer conceitos novos ou alterados e atualize o documento de domínio. A especificação deve usar esses termos canônicos.
3. Explorar a base de código. Identifique os módulos, interfaces, armazenamentos de dados e testes que a mudança afeta. Observe os padrões existentes a seguir. Referencie caminhos reais. O que o código faz hoje é evidência, não intenção: "seguir o padrão existente em src/x.ts" é em si uma escolha a ser confirmada com o usuário, registrada com sua fonte.
4. Projetar. Para cada decisão significativa, apresente 2–3 opções com trade-offs e uma recomendação; o usuário decide, e uma recomendação só conta quando ele a escolhe explicitamente. Para escolhas menores, agrupe-as em uma lista de confirmação em vez de decidir por conta própria. Considere modelo de dados e migrações, alterações de API/contrato, tratamento de erros, segurança, desempenho, observabilidade, implantação e reversão, e compatibilidade retroativa.
5. Registrar ADRs. Uma decisão merece um ADR se for difícil de reverter, afetar vários módulos, ou um futuro engenheiro perguntar "por que fizemos assim?". Escreva cada um em docs/adr/NNNN-titulo-em-kebab-case.md (próximo número livre, 4 dígitos) usando adr-template.md. Se um ADR substituir outro, atualize o status do antigo. Marque um ADR como Aceito somente quando o usuário confirmar a decisão; caso contrário, permanece Proposto.
6. Escrever a especificação em docs/specs/<titulo-em-kebab-case>.md usando spec-template.md. Divida o trabalho em tarefas pequenas, ordenadas e independentemente testáveis — cada uma com o(s) teste(s) que a comprovam. Preencha a seção Suposições da especificação a partir do livro; cada declaração de design deve ser rastreável a uma decisão do usuário ou aparecer lá como ❓.
7. Revisar com o usuário. Resuma a especificação e os ADRs, mostre os itens ❓ em aberto, peça aprovação e ajuste. Não defina a especificação como Aprovada enquanto qualquer ❓ afetar uma tarefa, critério de aceitação ou ADR.

Regras

• Respeite as convenções existentes do projeto se ele já possuir pastas ou modelos de especificação/ADR — use-os em vez disso.
• A especificação descreve o que e como verificar, com como suficiente para remover ambiguidade — não uma implementação linha por linha.
• Cada critério de aceitação deve mapear para pelo menos uma tarefa e teste.
• Mantenha-a tão curta quanto a mudança permitir.

Próximo passo

Recomende /handoff (para iniciar a implementação em uma sessão nova) ou /implement docs/specs/<arquivo>.md diretamente.