desenvolvimento-orientado-por-intenção

Desenvolvimento Orientado por Intenção

Produza critérios de aceitação úteis sem transformar a especificação em cerimônia. Inspecione primeiro o contexto disponível, exponha ambiguidades genuínas e escolha métodos de verificação que se ajustem ao trabalho e seu risco.

Quando Ativar

• O usuário pede para esclarecer uma funcionalidade, definir critérios de aceitação ou mitigar riscos antes da implementação
• A solicitação envolve segurança, autenticação, dados persistentes, migrações, APIs externas ou conformidade
• O usuário deseja preparar um artefato de transferência para outro agente ou equipe
• A solicitação é ambígua o suficiente para que o resultado esperado ainda não seja observável ou testável
• O usuário invoca explicitamente esta skill com /desenvolvimento-orientado-por-intenção

Não ative para edições triviais, correções simples de uma linha, sessões de depuração ativas, solicitações de revisão de código ou solicitações de implementação cujas condições de aceitação já estejam claras.

Como Funciona

1. Inspecione o contexto primeiro — lê o repositório, documentação, esquemas e infraestrutura de teste em busca de fatos técnicos antes de fazer qualquer pergunta, tratando restrições de produto/negócio como algo que apenas o usuário ou um artefato de produto pode fornecer
2. Escolha a profundidade — seleciona Captura Rápida (3-7 critérios, risco baixo/moderado) ou Brief de Aceitação Completo (segurança, dados, migração, alterações entre sistemas) com base no perfil de risco
3. Pergunte minimamente — faz apenas perguntas cujas respostas não podem ser inferidas e que alteram materialmente o escopo ou comportamento
4. Escreva critérios observáveis — cada AC-NNN descreve uma condição inicial, gatilho, resultado esperado, efeito colateral proibido, método de verificação e prioridade; sem palavras vagas como "corretamente" ou "com segurança" sem evidências
5. Prossiga ou transfira — para solicitações claras sem riscos bloqueadores, registra critérios e continua; para mudanças arriscadas, apresenta bloqueadores e aguarda confirmação
6. Lide com revisões — se um AC falhar durante a implementação devido a restrições arquiteturais, marque-o como [revisado], atualize o escopo ou método de verificação, incremente o número da revisão e reapresente apenas os critérios alterados

Exemplos

Captura Rápida — "Adicionar exportação CSV ao painel"

Objetivo: Usuários autenticados podem baixar dados do painel como um arquivo CSV.
No escopo: Exportação das linhas atualmente filtradas; nome do arquivo inclui data.
Fora do escopo: Exportações agendadas, entrega por e-mail, formato Excel.
Suposições: Contagem máxima de linhas é inferior a 10k; não há PII nos campos exportados.

AC-001: Exportação gera arquivo com cabeçalhos corretos
- Cenário: usuário autenticado, pelo menos uma linha de dados visível
- Ação: clicar em "Exportar CSV"
- Esperado: o navegador baixa arquivo com colunas [id, nome, criado_em]
- Não deve: expor campos internos ou linhas pertencentes a outros usuários
- Verificação: teste de integração automatizado + verificação manual do esquema
- Prioridade: Obrigatório

Gatilho para Brief de Aceitação Completo — "Migrar autenticação de usuário para OAuth"

Alteração de autenticação + dependência externa + dados de sessão existentes → Brief Completo com tabela de Revisão de Risco, decisões bloqueadoras sobre estratégia de invalidação de sessão e AC de reversão explícita.

Revisão de especificação existente — usuário cola um PRD

A skill revisa em busca de limites de escopo ausentes, requisitos não verificáveis ("o sistema deve ser rápido"), e suposições silenciosas, depois retorna critérios corrigidos ou suplementares sem recomeçar a descoberta.

Regras Operacionais

1. Inspecione o repositório disponível, documentação, issue, design e contexto de teste antes de pedir fatos técnicos que podem ser descobertos localmente.
2. Não infira restrições de produto ou negócio a partir do código. Regras de negócio, obrigações de conformidade e regulatórias, SLAs contratuais, preços, política de retenção de dados, priorização e usuários-alvo não podem ser lidos de um repositório. Trate-os como desconhecidos até que o usuário os forneça ou um artefato de produto autoritativo (PRD, contrato, documento de política) os declare. Registre-os como suposições sinalizadas para confirmação, nunca como fatos descobertos. O repositório diz como o sistema se comporta hoje, não o que o negócio exige que ele faça.
3. Faça apenas perguntas cujas respostas são necessárias e não podem ser inferidas com segurança. Agrupe perguntas curtas e relacionadas quando isso economizar turnos desnecessários.
4. Não bloqueie a implementação por padrão. Quando o usuário pediu para implementar uma mudança suficientemente clara, registre brevemente as principais suposições e critérios de aceitação, depois prossiga ou passe para o fluxo de trabalho de implementação.
5. Exija confirmação explícita do usuário antes de prosseguir apenas quando uma decisão não resolvida pode criar exposição material de segurança, perda de dados, migração irreversível, quebra contratual/de API, custo significativo ou ação externa destrutiva.
6. Não escreva um documento de aceitação em um repositório, altere arquivos do projeto, crie um branch, faça commit ou invoque outra skill a menos que o usuário solicite ou o fluxo de trabalho ativo do repositório exija explicitamente.
7. Trate testes automatizados como evidência, não verdade. Prefira automação quando confiável e proporcionada; permita verificação manual de UX, acessibilidade, segurança, legal ou operacional onde a automação não pode estabelecer o resultado.
8. Nunca inclua segredos reais, credenciais, tokens, chaves privadas, dados pessoais ou payloads de produção sensíveis em critérios de aceitação, fixtures, exemplos ou artefatos salvos. Use valores editados ou sintéticos.
9. Não execute testes destrutivos, migrações, sondas de segurança, testes de carga, chamadas externas pagas ou operações contra dados de produção/ao vivo sem autorização explícita e um ambiente seguro identificado.
10. Quando um critério de aceitação não puder ser satisfeito devido a uma restrição arquitetural, de plataforma ou externa descoberta durante a implementação, não o descarte silenciosamente nem o contorne. Atualize o critério afetado (marque-o como [revisado], declare a restrição e ajuste o escopo ou método de verificação), incremente o número da revisão e reapresente apenas os critérios alterados ao usuário antes de continuar. Exija confirmação explícita apenas se a revisão alterar uma decisão bloqueadora ou reduzir materialmente as garantias de segurança ou correção.

Escolha a Profundidade

Use a menor saída útil.

Captura Rápida

Use para uma mudança clara, mas não trivial, com risco baixo ou moderado. Produza:

• Objetivo
• No escopo / Fora do escopo
• Suposições
• 3-7 critérios de aceitação com métodos de verificação
• Perguntas bloqueadoras, se houver

Não atrase a implementação para aprovação, a menos que exista um risco bloqueador das regras operacionais ou o usuário tenha pedido especificamente uma especificação primeiro.

Brief de Aceitação Completo

Use para mudanças ambíguas, entre sistemas, sensíveis à segurança, de alteração de dados, migração, conformidade ou alto custo, ou quando o usuário solicitar um artefato de transferência. Produza o modelo completo abaixo e solicite confirmação para decisões bloqueadoras não resolvidas antes da implementação arriscada.

Revisão de Especificação Existente

Quando o usuário já forneceu um PRD, issue, plano ou critérios de aceitação:

1. Revise-o em vez de recomeçar a descoberta.
2. Identifique limites de escopo ausentes, suposições inseguras, contradições e requisitos não verificáveis.
3. Retorne critérios corrigidos ou suplementares.

Fluxo de Trabalho

1. Estabelecer Objetivo e Risco

Extraia ou pergunte sobre:

• O resultado observável para o usuário ou sistema.
• Os atores afetados.
• A principal consequência de falha.
• Dimensões de risco que realmente se aplicam: segurança/privacidade, dados persistentes, compatibilidade/API, migração, dependências externas, custo, concorrência, desempenho, usabilidade/acessibilidade.

Evite fazer perguntas genéricas sobre riscos irrelevantes.

2. Descobrir Contexto

Quando artefatos locais ou conectados estiverem disponíveis, inspecione apenas o necessário:

• Comportamento existente e arquivos ou interfaces diretamente relacionados.
• Convenções do repositório, documentação do produto, contratos de API, esquemas de dados ou histórico de migração.
• Infraestrutura de verificação existente e comandos realistas.
• Dependências externas e se são testáveis de forma isolada.

Registre fatos descobertos separadamente das suposições fornecidas pelo usuário. Se o contexto não puder ser inspecionado, diga o que é desconhecido e faça perguntas focadas.

O repositório revela fatos técnicos — como o sistema se comporta hoje, suas convenções e seus contratos. Ele não revela restrições de produto ou negócio: regras de negócio, obrigações de conformidade e regulatórias, SLAs contratuais, preços, política de retenção de dados, priorização e usuários-alvo. Nunca reconstrua estas a partir do código ou nomenclatura. Capture-as apenas do usuário ou de um artefato de produto autoritativo e liste-as como suposições a confirmar até então.

3. Definir Escopo

Declare:

• Objetivo: uma frase descrevendo o resultado pretendido.
• No escopo: comportamento que esta mudança deve entregar.
• Fora do escopo: trabalho adjacente tentador explicitamente excluído.
• Suposições: afirmações ainda não comprovadas.
• Decisões bloqueadoras: escolhas não resolvidas que afetam materialmente a segurança ou o comportamento.

4. Escrever Critérios de Aceitação

Use AC-001, AC-002, e assim por diante. Cada critério deve descrever comportamento observável e um método de verificação apropriado; critérios e testes não são obrigados a mapear um-para-um.

Para cada critério aplicável, inclua:

• Cenário ou condição inicial.
• Ação ou gatilho.
• Comportamento observável esperado.
• Efeito colateral proibido quando significativo.
• Método de verificação: teste automatizado, verificação de integração, revisão manual de UX, verificação de acessibilidade, revisão de segurança, verificação operacional ou aceitação das partes interessadas.
• Restrição de ambiente/segurança quando a verificação puder afetar dados, serviços, custo ou segredos.
• Prioridade: obrigatório, importante ou opcional.

Não use palavras como "corretamente", "com segurança", "rápido", "intuitivo" ou "robusto" sem definir evidências observáveis ou registrá-las como um julgamento de revisão humana.

5. Cobrir Apenas Limites Relevantes

Considere estas categorias, mas inclua apenas as categorias que se aplicam:

Categoria	Incluir quando	Evidência típica
Caminho feliz	Comportamento novo ou alterado visível ao usuário	Fluxo de trabalho bem-sucedido ou transição de estado
Validação	A mudança aceita entrada	Entrada malformada ou de valor limite rejeitada sem mutação
Autorização/privacidade	Dados ou ações têm limites de acesso	Acesso negado e nenhuma divulgação sensível
Persistência/migração	Dados armazenados ou esquemas mudam	Leitura reversa, migração, reversão ou comportamento de backup
Compatibilidade	APIs públicas, arquivos, eventos ou clientes podem quebrar	Contrato existente ou fixture permanece válido
Recuperação de falha	Rede, serviço ou falha assíncrona existe	Nenhum estado parcial ou comportamento de repetição/rebaixamento claro
Idempotência/concorrência	Repetições ou gravações simultâneas são plausíveis	Nenhum efeito colateral duplicado ou estado final inválido
Desempenho	Um limite de usuário ou serviço importa	Condições de medição e limite definidos
UX/acessibilidade	Uma pessoa interage com o resultado	Teclado, feedback, recuperação de erro, revisão visual/manual

6. Apresentar e Continuar

• Para uma solicitação de esclarecimento/especificação, apresente o brief e peça decisões apenas sobre os bloqueadores listados.
• Para uma solicitação de implementação sem bloqueador, apresente um resumo compacto de critérios como parte do trabalho e continue com a implementação.
• Para transferência para outro agente ou equipe, inclua contexto e detalhes de verificação suficientes para que eles ajam sem inventar requisitos.
• Salve o brief em um arquivo apenas quando solicitado. Use um caminho aprovado pelo repositório quando existir; caso contrário, pergunte ou declare o destino escolhido antes de escrever.

Modelo de Saída

Use este modelo para um Brief de Aceitação Completo. Omita seções irrelevantes para Captura Rápida.

# Brief de Aceitação: <Nome da Mudança>

**Status:** Rascunho | Aprovado | Implementado | Verificado
**Revisão:** <número>
**Preparado para:** <usuário/equipe/agente, quando conhecido>
**Aprovação necessária antes de trabalho arriscado:** Sim | Não - <motivo>

## Registro de Revisões

| Rev | Data | Critérios alterados | Motivo |
| --- | --- | --- | --- |
| 1 | <data> | — | Rascunho inicial |

## Objetivo

<Uma frase de resultado observável.>

## Escopo

**No escopo**
- <comportamento incluído>

**Fora do escopo**
- <trabalho adjacente excluído>

## Contexto

**Fatos descobertos** (técnicos, verificados do repositório ou artefato)
- <como o sistema se comporta hoje, convenções, contratos>

**Restrições de produto/negócio** (fornecidas pelo usuário ou artefato de produto, nunca inferidas do código)
- <regra de negócio, obrigação de conformidade/SLA, política de retenção, prioridade, usuário-alvo — ou "nada fornecido ainda">

**Suposições**
- <afirmação não verificada a confirmar ou validar>

**Dependências e restrições**
- <serviço externo, convenção local, obrigação de compatibilidade, limite de ambiente>

## Revisão de Risco

| Área de risco | Aplica-se? | Tratamento exigido |
| --- | --- | --- |
| Segurança/privacidade | Sim/Não | <edição, autorização, revisão, etc.> |
| Dados persistentes/migração | Sim/Não | <compatibilidade, backup, reversão, etc.> |
| Efeitos externos/custo | Sim/Não | <sandbox/ambiente de teste/autorização> |
| Compatibilidade/API | Sim/Não | <contrato a preservar ou versionar> |
| UX/acessibilidade | Sim/Não | <evidência manual ou automatizada> |

## Critérios de Aceitação

### AC-001: <comportamento observável>
- **Cenário:** <condição inicial>
- **Ação:** <gatilho único>
- **Esperado:** <resultado observável>
- **Não deve:** <efeito colateral proibido, se aplicável>
- **Verificação:** <método e evidência pretendida>
- **Ambiente/segurança:** <restrições, se aplicável>
- **Prioridade:** Obrigatório | Importante | Opcional

## Decisões Bloqueadoras

- [ ] <apenas decisões que impedem progresso seguro ou correto>

## Plano de Verificação

| Critério | Evidência de verificação | Status |
| --- | --- | --- |
| AC-001 | <teste/verificação/revisão comando ou tipo de evidência> | Pendente |

Exemplos de Aprovação/Reprovação

Use estes para julgar se a skill realmente produziu um brief verificável, e não prosa de planejamento.

Um critério de aceitação reprovado

AC-001: A exportação funciona corretamente e é segura.

Reprova — "funciona corretamente" e "segura" não são observáveis, não há cenário, gatilho, resultado esperado...