Skills

Skills são guias de especialidade técnica e funcional. Cada skill define objetivo, fontes obrigatórias e a sequência de execução para um tipo específico de trabalho.

O que uma skill faz e o que não faz

Uma skill orienta como executar dentro de um domínio. Ela não substitui o workflow, não define a ordem das tasks e não valida qualidade; isso é responsabilidade do Quality Gate.

A relação é clara:

Princípio de execução comum

Todo uso de skill segue o mesmo ciclo:

Analisar → Revisar → Mapear → Planejar → Implementar/Executar → Testar → Validar

Todo fechamento de skill exige:

1. Revisão das fontes oficiais em Docs/
2. Mapeamento de impacto antes da execução
3. Execução do trabalho técnico
4. Teste do resultado
5. Validação final com Quality Gate aprovado
6. Evidências registradas em Docs/tasks.md e Docs/control.md

Qual skill usar para cada demanda

Fontes de verdade por domínio

Cada skill lê documentos específicos de Docs/ como ponto de partida:

Catálogo completo de skills

Implementação

Skills/implementation.md

Implementar entrega planejada com aderência a documentos e contratos.

Fontes: Docs/plan.md · Docs/tasks.md · Docs/project.md

1. Ler task e critério de aceite
2. Revisar documentos-fonte do escopo
3. Mapear impactos em módulo, fluxo, contrato e dados
4. Planejar implementação
5. Executar
6. Testar
7. Validar com Dev e IA

Refatoração

Skills/refactoring.md

Melhorar estrutura interna preservando comportamento e contratos.

Fontes: Docs/architecture.md · Docs/structure.md · Docs/contract.yaml

1. Identificar riscos de regressão
2. Definir plano de refatoração
3. Garantir cobertura mínima de testes
4. Refatorar por etapas
5. Validar compatibilidade

Testes

Skills/tests.md

Validar comportamento, contrato e regressão.

Fontes: Docs/tasks.md · Docs/user-stories.md · Docs/contract.yaml · Quality/realistic-tests.md · Quality/gate.md

1. Mapear cenários críticos e critérios de aceite
2. Priorizar testes realistas com infraestrutura de produção ou equivalente
3. Usar Testcontainers por padrão para integração de backend/API
4. Validar interface com e2e em fluxos críticos
5. Para mobile: validar em BrowserStack (ou alternativa) e dispositivo físico local
6. Evitar mock/stub/placeholder, salvo exceção formal registrada na task
7. Executar suíte
8. Registrar evidências no Quality Gate

Contratos

Skills/contracts.md

Criar ou revisar contratos formais de API, design system e tokens.

Fontes: Docs/contract.yaml · Docs/design-system.md · Docs/tokens.json

Tipos de contrato no framework:

• API → Docs/contract.yaml
• Design system → Docs/design-system.md
• Tokens → Docs/tokens.json

1. Identificar fonte principal do contrato
2. Mapear impacto em consumidores
3. Atualizar contrato
4. Validar consumo real

UI/UX

Skills/ui-ux.md

Implementar ou corrigir interface com consistência visual e funcional.

Fontes: Docs/pages.md · Docs/flow.md · Docs/design-system.md · Docs/tokens.json

1. Revisar tela ou componente e estados
2. Comparar com fluxo e padrões visuais
3. Atualizar ou criar protótipo HTML em `Prototype/` quando houver impacto de interface
4. Implementar ajuste
5. Testar responsividade, estados e acessibilidade

Fluxo

Skills/flow.md

Ajustar navegação e transições entre telas.

Fontes: Docs/flow.md · Docs/pages.md

1. Mapear entradas, transições e exceções
2. Implementar navegação e estados
3. Testar caminhos principais e alternativos

Integração

Skills/integration.md

Implementar ou corrigir comunicação entre módulos ou serviços externos.

Fontes: Docs/contract.yaml · Docs/architecture.md · Docs/entities.md

1. Definir requisição/resposta e autenticação
2. Isolar integração em módulo apropriado
3. Validar sucesso, falha, timeout e fallback quando aplicável

Deploy

Skills/deploy.md

Publicar mudanças com segurança operacional.

Fontes: Docs/deploy.md · Docs/architecture.md · Docs/control.md

1. Revisar pipeline e variáveis de ambiente
2. Executar publicação
3. Validar saúde do ambiente
4. Registrar resultado em `Docs/control.md`

Logs

Skills/logs.md

Padronizar e usar observabilidade para diagnóstico.

Fontes: Docs/deploy.md · Docs/architecture.md

1. Classificar erro e contexto
2. Identificar origem
3. Corrigir lógica ou instrumentação
4. Validar sinal após ajuste

Scripts

Skills/scripts.md

Automatizar tarefas operacionais com baixo risco.

Fontes: Docs/structure.md · Docs/deploy.md · Quality/gate.md

1. Definir entradas, saídas e efeitos colaterais
2. Implementar script idempotente quando possível
3. Priorizar scripts reutilizáveis para validação de testes e contratos
4. Testar em ambiente isolado
5. Registrar comandos e evidências para reprodução no Quality Gate

Curl

Skills/curl.md

Validar endpoints com chamadas reproduzíveis.

Fontes: Docs/contract.yaml · Quality/gate.md

1. Definir autenticação e payload
2. Executar chamadas
3. Comparar resposta com contrato
4. Versionar comandos em scripts reproduzíveis quando possível
5. Registrar evidências no Quality Gate da task

User Stories

Skills/user-stories.md

Converter histórias em entregas validáveis.

Fontes: Docs/user-stories.md · Docs/project.md · Docs/tasks.md

1. Revisar história e critério de aceite
2. Mapear impactos cruzados
3. Conectar implementação ao plano e tarefas
4. Validar comportamento esperado

Padrão de frontmatter por skill

Todo arquivo de skill usa frontmatter YAML mínimo para identificação e rastreabilidade:

---
nome: "Nome da skill"
objetivo: "Objetivo principal em uma frase"
fontes:
  - "Docs/documento-principal.md"
  - "Docs/documento-complementar.md"
---

Regras que não mudam

1. Skill é guia de especialidade; não substitui workflow nem Quality Gate
2. Toda skill deve consultar as fontes oficiais em Docs/ antes de executar
3. Toda skill deve mapear impacto antes da execução
4. Toda entrega técnica encerra com Quality Gate aprovado
5. Evidências registradas em Docs/tasks.md e Docs/control.md