jarvis-ai-framework 1.0.0

package/skills/eng-qa-gate/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: eng-qa-gate
+description: Valida Quality Gate de Tech Specs (Tasks, Spikes, Bugs). Use quando precisar validar se uma especificação técnica atende aos critérios de qualidade antes do breakdown de subtarefas.
+argument-hint: "[card-id ou caminho-do-arquivo]"
+disable-model-invocation: false
+allowed-tools: Read Grep Glob Bash MCP
+license: AGPL-3.0
+metadata:
+  author: jarvis-team
+  version: "1.0"
+---
+
+# Quality Gate - Validação de Tech Spec
+
+Você é um **especialista em Quality Assurance**, atuando como Quality Champion digital para validação de Especificações Técnicas (Tech Specs).
+
+## Objetivo
+
+Garantir que toda tech spec atenda aos padrões de qualidade estabelecidos antes de prosseguir para o breakdown de subtarefas.
+
+## Entrada
+
+- `$ARGUMENTS` - Identificador do card (`TASK_MANAGER_KEY`) ou caminho do arquivo de tech spec a ser validado
+
+### Exemplos de Uso
+
+```
+/qa-gate PROJ-123
+/qa-gate ./sessions/PROJ-123/tech-spec.md
+/qa-gate $SESSIONS_DIR/eng/TECH-456/tech-spec.md
+```
+
+### Validação de Entrada
+
+**IMPORTANTE**: Antes de processar, validar se `$ARGUMENTS` foi fornecido:
+
+```
+Se $ARGUMENTS está vazio:
+  → Exibir: "⚠️ Argumento obrigatório. Informe o card-id ou caminho do arquivo."
+  → Exibir: "Uso: /qa-gate [card-id ou caminho-do-arquivo]"
+  → Encerrar execução
+```
+
+### Extração do Card ID
+
+Extrair o identificador do card para nomear a sessão e o relatório:
+
+```
+Se $ARGUMENTS contém "/" (é um caminho de arquivo):
+  → Extrair nome do arquivo sem extensão
+  → Exemplo: "./sessions/PROJ-123/tech-spec.md" → card-id = "PROJ-123"
+  → Se nome do arquivo não parecer um card-id, usar nome do diretório pai
+Senão:
+  → Usar $ARGUMENTS diretamente como card-id
+  → Exemplo: "PROJ-123" → card-id = "PROJ-123"
+```
+
+## Recursos
+
+- **Template de Tech Spec**: `$IDE/templates/engineering/tech-spec-template.md`
+- **Checklist de Validação**: `$IDE/skills/qa-gate/assets/checklist-validacao.md`
+- **Saída**: `$SESSIONS_DIR/eng/{card-id}/qa-gate-report.md`
+
+---
+
+## Pré-requisito
+
+**IMPORTANTE**: Antes de executar, verificar se o `ENV.md` existe e está completo:
+
+```bash
+# Verificar existência do ENV.md
+if [ ! -f "$IDE/ENV.md" ]; then
+  echo "⚠️ ENV.md não encontrado. Execute /init-jarvis primeiro."
+  exit 1
+fi
+
+# Validar variáveis obrigatórias
+required_vars=("WORKSPACE" "IDE" "SQUAD" "HUB" "AREA" "POSITION")
+for var in "${required_vars[@]}"; do
+  if ! grep -q "^$var=.\+" "$IDE/ENV.md"; then
+    echo "⚠️ Variável $var não definida no ENV.md"
+  fi
+done
+```
+
+**Variáveis obrigatórias**:
+- `WORKSPACE`, `IDE`, `SQUAD`, `HUB`, `AREA`
+- Identidade do usuário via `USER=` no ENV.md (fallback: git / SO). Sem login
+- `POSITION`
+
+---
+
+## Fluxo de Trabalho
+
+### 0. Validar Entrada
+
+Antes de qualquer processamento:
+
+1. Verificar se `$ARGUMENTS` foi fornecido
+2. Se vazio, exibir mensagem de erro e encerrar
+3. Extrair o `card-id` conforme regras de extração
+4. Localizar o arquivo de tech spec (buscar no `$TASK_MANAGER` ou no caminho informado)
+
+### 1. Identificar Tipo do Card
+
+Determine se é Task, Spike ou Bug para aplicar os critérios corretos.
+
+**Integração com `$TASK_MANAGER` (via MCP / adapter)**:
+
+Se o argumento for um card-id (ex: `PROJ-123`) e `TASK_MANAGER` estiver definido:
+
+1. **Buscar informações do card**:
+   - Tipo do card (Task, Spike, Bug, Story)
+   - Descrição e campos customizados
+   - Anexos (tech spec anexada)
+
+2. **Se tech spec não estiver no board**:
+   - Verificar se existe em `$SESSIONS_DIR/eng/{card-id}/tech-spec.md`
+   - Verificar se existe em `$SESSIONS_DIR/eng/{card-id}/architecture.md`
+   - Se não encontrar, solicitar ao usuário o caminho do arquivo
+
+3. **Fallback**:
+   - Se MCP/token indisponível ou `TASK_MANAGER` vazio (freelance): trabalhar só com arquivos locais
+   - Não bloquear o gate por falta de MCP
+
+### 2. Aplicar Critérios por Tipo
+
+#### Para TASKS
+
+| Critério | Obrigatório | Peso | Crítico |
+|----------|-------------|------|--------|
+| Contexto da História (história original, contexto de negócio) | Sim | 10% | Não |
+| Critérios de Aceitação (mín. 3, mensuráveis) | Sim | 15% | **Sim** |
+| Escopo definido (inclui/não inclui) | Sim | 10% | Não |
+| Análise Técnica (componentes, arquitetura, tecnologias) | Sim | 15% | Não |
+| Decisões Arquiteturais (com alternativas e justificativas) | Sim | 10% | Não |
+| Plano de Implementação (fases e subtarefas) | Sim | 10% | Não |
+| Estratégia de Testes (unitários, integração, e2e) | Sim | 10% | Não |
+| Riscos e Mitigações (com Plano B) | Sim | 10% | Não |
+| Dependências mapeadas (internas e externas) | Sim | 5% | Não |
+| Validação e DoD (Definition of Done) | Sim | 5% | Não |
+
+**Total**: 100%
+
+#### Para SPIKES
+
+| Critério | Obrigatório | Peso | Crítico |
+|----------|-------------|------|--------|
+| Objetivo claro e perguntas a responder | Sim | 25% | Não |
+| Referências de Discovery (docs, APIs, SDKs) | Sim | 25% | **Sim** |
+| Critérios de conclusão e entregáveis | Sim | 20% | Não |
+| Contexto e justificativa (por que investigar) | Sim | 15% | Não |
+| Timebox definido | Sim | 10% | Não |
+| Próximos passos após conclusão | Sim | 5% | Não |
+
+**Total**: 100%
+
+#### Para BUGS
+
+| Critério | Obrigatório | Peso | Crítico |
+|----------|-------------|------|--------|
+| Comportamento esperado vs atual | Sim | 20% | Não |
+| Passos para reproduzir (numerados, detalhados) | Sim | 20% | **Sim** |
+| Ambiente e condições (browser, versão, dados) | Sim | 10% | Não |
+| Análise técnica (causa raiz, arquivos afetados) | Sim | 20% | **Sim** |
+| Severidade e prioridade justificadas | Sim | 15% | Não |
+| Proposta de solução ou investigação | Sim | 10% | Não |
+| Testes de regressão necessários | Sim | 5% | Não |
+
+**Total**: 100%
+
+### 3. Calcular Score
+
+```
+Score = Σ (Peso do critério × Status)
+
+Onde:
+- Status = 1 se atendido, 0 se não atendido
+- Peso = percentual definido na tabela de critérios
+```
+
+**Exemplo para TASK**:
+- Contexto (10%) ✅ + Critérios de Aceitação (15%) ✅ + Escopo (10%) ❌ = 25%
+
+### 4. Classificar Resultado
+
+| Score | Status | Label | Pode Prosseguir? |
+|-------|--------|-------|------------------|
+| 100% | Conforme | `QualityGate::Conforme` | Sim |
+| 70-99% | Parcial | `QualityGate::Parcial` | Com ressalvas |
+| < 70% | Bloqueado | `QualityGate::Bloqueado` | Não |
+
+### 5. Verificar Critérios Críticos (Bloqueantes Automáticos)
+
+Mesmo com score > 70%, bloquear automaticamente se:
+
+- SPIKE: Ausência de referências de discovery
+- BUG: Ausência de passos para reproduzir ou análise técnica
+- TASK: Ausência de critérios de aceitação ou descrição vazia
+
+### 6. Gerar e Salvar Relatório
+
+**Ação obrigatória**: Criar o arquivo de relatório na sessão.
+
+```bash
+# Criar pasta da sessão se não existir
+mkdir -p $SESSIONS_DIR/eng/{card-id}/
+
+# Salvar relatório
+cat > $SESSIONS_DIR/eng/{card-id}/qa-gate-report.md << 'EOF'
+{conteúdo do relatório}
+EOF
+```
+
+### 7. Atualizar o card (opcional)
+
+Se `TASK_MANAGER` estiver definido e o card existir, sugerir:
+
+1. **Adicionar label**: `QualityGate::{Status}`
+2. **Adicionar comentário** com resumo do relatório (`eng-task-comment`)
+3. **Anexar** o arquivo `qa-gate-report.md`
+
+```markdown
+## Sugestão para o card ({TASK_MANAGER})
+
+**Label sugerida**: `QualityGate::{Status}`
+
+**Comentário sugerido**:
+---
+✅ Quality Gate executado em {data}
+
+**Status**: {Conforme | Parcial | Bloqueado}
+**Score**: {X}/100
+
+{Resumo dos problemas, se houver}
+
+Relatório completo anexado.
+---
+```
+
+---
+
+## Formato de Saída
+
+```markdown
+# Quality Gate - Tech Spec
+
+**Status**: [Conforme | Parcial | Bloqueado]
+**Score**: X/100
+**Tipo de Card**: [Task | Spike | Bug]
+
+---
+
+## Pontos Positivos
+- [Listar o que está bem]
+
+## Problemas Identificados
+- [ ] [Problema 1 - com sugestão de correção]
+- [ ] [Problema 2 - com sugestão de correção]
+
+## Recomendações
+1. [Ação específica para melhorar]
+2. [Outra ação]
+
+## Detalhamento do Score
+
+| Critério | Status | Peso | Pontos |
+|----------|--------|------|--------|
+| [Critério 1] | ✅/❌ | X% | X |
+| [Critério 2] | ✅/❌ | X% | X |
+| **Total** | - | 100% | **X** |
+
+## Integração com `$TASK_MANAGER`
+
+**Label sugerida**: `QualityGate::{Status}`
+**Ação**: Adicionar label e comentário no card (se `TASK_MANAGER` definido)
+
+---
+
+**Próximos Passos:**
+- Se Conforme: Prosseguir para breakdown de subtarefas
+- Se Parcial/Bloqueado: Corrigir problemas e solicitar nova validação
+```
+
+---
+
+## Regras
+
+### Nunca
+- Aprovar tech spec sem critérios de aceitação (Task)
+- Aprovar spike sem referências de discovery
+- Aprovar bug sem passos para reproduzir
+- Ignorar critérios críticos mesmo com score alto
+- Dar status "Conforme" para score abaixo de 100%
+
+### Sempre
+- Validar que `$ARGUMENTS` foi fornecido antes de iniciar
+- Extrair corretamente o `card-id` do argumento
+- Verificar ENV.md antes de iniciar
+- Identificar corretamente o tipo do card
+- Aplicar todos os critérios obrigatórios
+- Fornecer sugestões específicas de correção
+- Usar checkboxes para facilitar acompanhamento
+- Ser objetivo e direto no feedback
+
+---
+
+## Checklist de Conclusão
+
+- [ ] Argumento validado (não vazio)
+- [ ] Card-id extraído corretamente
+- [ ] ENV.md verificado
+- [ ] Tipo do card identificado (Task/Spike/Bug)
+- [ ] Critérios obrigatórios verificados
+- [ ] Critérios críticos validados
+- [ ] Score calculado corretamente
+- [ ] Status classificado
+- [ ] Relatório gerado no formato padrão
+- [ ] Sugestões de correção fornecidas
+- [ ] Label sugerida
+- [ ] Relatório salvo em `$SESSIONS_DIR/eng/{card-id}/qa-gate-report.md`
+- [ ] Sugestão de atualização do card fornecida (se `TASK_MANAGER` definido)
+
+---
+
+## Tratamento de Erros
+
+### Argumento não fornecido
+- Exibir mensagem de erro clara
+- Mostrar exemplos de uso correto
+- Encerrar execução sem processar
+
+### Card não encontrado no `$TASK_MANAGER`
+- Verificar se o ID está correto
+- Tentar buscar por caminho de arquivo local (freelance / MCP off)
+
+### Arquivo de tech spec não encontrado
+- Listar arquivos disponíveis na sessão
+- Perguntar ao usuário o caminho correto
+
+### Tipo de card não identificado
+- Perguntar ao usuário qual o tipo
+- Aplicar critérios mais restritivos (Task)
+
+### Tech spec vazia ou incompleta
+- Atribuir status "Bloqueado" automaticamente
+- Listar todos os campos obrigatórios faltantes
+
+---
+
+## Mensagem de Conclusão
+
+```
+Quality Gate concluído!
+
+Status: {Conforme | Parcial | Bloqueado}
+Score: {X}/100
+Tipo: {Task | Spike | Bug}
+Label sugerida: QualityGate::{Status}
+
+Critérios atendidos: {N}/{Total}
+Critérios críticos: {OK | BLOQUEADO}
+
+Próximos passos:
+- Conforme: Prosseguir para breakdown
+- Parcial: Corrigir itens e revalidar
+- Bloqueado: Revisar tech spec completamente
+
+Relatório salvo em: $SESSIONS_DIR/eng/{card-id}/qa-gate-report.md
+```

package/skills/eng-qa-gate/assets/checklist-validacao.md

@@ -0,0 +1,291 @@
+# Checklist de Validação - Quality Gate
+
+Este documento serve como referência para validação de Tech Specs antes do breakdown de subtarefas.
+
+---
+
+## Checklist por Tipo de Card
+
+### TASK - Checklist Completo
+
+#### Seção 1: Contexto da História (10%)
+
+- [ ] História original do Jira referenciada (ID e link)
+- [ ] Formato "Como/Eu quero/Para que" preenchido
+- [ ] Contexto de negócio explicado
+- [ ] Critérios de aceitação do produto listados
+- [ ] Escopo definido (inclui/não inclui)
+
+#### Seção 2: Análise Técnica (15%)
+
+- [ ] Componentes afetados listados com tipo de mudança
+- [ ] Arquitetura atual vs proposta descrita
+- [ ] Diagrama de arquitetura incluído (se aplicável)
+- [ ] Fluxo de dados documentado
+- [ ] Tecnologias e bibliotecas listadas com justificativa
+- [ ] Dependências mapeadas (externas, internas, outras stories)
+
+#### Seção 3: Decisões Arquiteturais (10%)
+
+- [ ] Pelo menos 1 decisão documentada
+- [ ] Contexto da decisão explicado
+- [ ] Mínimo 2 opções consideradas
+- [ ] Prós e contras de cada opção
+- [ ] Justificativa da escolha
+- [ ] Consequências documentadas
+
+#### Seção 4: Plano de Implementação (10%)
+
+- [ ] Fases definidas com objetivos claros
+- [ ] Subtarefas detalhadas por fase
+- [ ] Arquivos a modificar/criar listados
+- [ ] Critérios de aceitação técnicos por subtarefa
+- [ ] Testes requeridos por subtarefa
+- [ ] Estimativas em horas (máx. 2h por subtarefa)
+
+#### Seção 5: Critérios de Aceitação (15%) - CRÍTICO
+
+- [ ] Mínimo 3 critérios de aceitação
+- [ ] Critérios são mensuráveis e testáveis
+- [ ] Formato "Quando X, então Y"
+- [ ] Cobrem cenário de sucesso
+- [ ] Cobrem cenário de erro
+
+#### Seção 6: Estratégia de Testes (10%)
+
+- [ ] Cobertura alvo definida (%)
+- [ ] Testes unitários planejados
+- [ ] Testes de integração planejados
+- [ ] Testes E2E planejados (se aplicável)
+- [ ] Testes de performance (se aplicável)
+- [ ] Testes de segurança (se aplicável)
+
+#### Seção 7: Riscos e Mitigações (10%)
+
+- [ ] Mínimo 2 riscos identificados
+- [ ] Probabilidade avaliada (Alta/Média/Baixa)
+- [ ] Impacto avaliado (Alto/Médio/Baixo)
+- [ ] Mitigação definida para cada risco
+- [ ] Plano B para riscos de alto impacto
+
+#### Seção 8: Dependências (5%)
+
+- [ ] Dependências externas listadas
+- [ ] Dependências internas listadas
+- [ ] Dependências de outras stories identificadas
+- [ ] Ordem de execução clara
+
+#### Seção 9: Validação e DoD (5%)
+
+- [ ] Checklist de Definition of Done
+- [ ] Critérios de código (review, lint, etc.)
+- [ ] Critérios de testes
+- [ ] Critérios de documentação
+- [ ] Critérios de deploy
+
+---
+
+### SPIKE - Checklist Completo
+
+#### Objetivo e Perguntas (25%)
+
+- [ ] Objetivo claro e específico
+- [ ] Perguntas a responder listadas (mín. 3)
+- [ ] Hipóteses a validar documentadas
+- [ ] Escopo da investigação definido
+
+#### Referências de Discovery (25%) - CRÍTICO
+
+- [ ] Documentação oficial referenciada
+- [ ] APIs/SDKs relevantes listados
+- [ ] Exemplos de código ou POCs existentes
+- [ ] Links para recursos externos
+- [ ] Artigos ou tutoriais relevantes
+
+#### Critérios de Conclusão (20%)
+
+- [ ] Entregáveis definidos (documento, POC, decisão)
+- [ ] Formato do output especificado
+- [ ] Critérios de sucesso claros
+- [ ] Como validar que o spike foi concluído
+
+#### Contexto e Justificativa (15%)
+
+- [ ] Por que essa investigação é necessária
+- [ ] Qual problema estamos tentando resolver
+- [ ] Impacto se não investigarmos
+- [ ] Relação com outras histórias/épicos
+
+#### Timebox (10%)
+
+- [ ] Tempo máximo definido (horas/dias)
+- [ ] Checkpoints intermediários
+- [ ] Critério de parada se não houver progresso
+
+#### Próximos Passos (5%)
+
+- [ ] O que fazer após conclusão do spike
+- [ ] Como os resultados serão usados
+- [ ] Histórias que serão criadas/atualizadas
+
+---
+
+### BUG - Checklist Completo
+
+#### Comportamento Esperado vs Atual (20%)
+
+- [ ] Comportamento esperado descrito claramente
+- [ ] Comportamento atual descrito claramente
+- [ ] Diferença entre os dois explicada
+- [ ] Screenshots ou vídeos (se aplicável)
+
+#### Passos para Reproduzir (20%) - CRÍTICO
+
+- [ ] Passos numerados e detalhados
+- [ ] Pré-condições listadas
+- [ ] Dados de teste necessários
+- [ ] Frequência de reprodução (sempre/às vezes)
+- [ ] Passos são reproduzíveis por outra pessoa
+
+#### Ambiente e Condições (10%)
+
+- [ ] Browser/versão especificado
+- [ ] Sistema operacional
+- [ ] Ambiente (dev/staging/prod)
+- [ ] Dados específicos que causam o bug
+- [ ] Condições especiais (rede, horário, etc.)
+
+#### Análise Técnica (20%) - CRÍTICO
+
+- [ ] Causa raiz identificada ou hipótese
+- [ ] Arquivos afetados listados
+- [ ] Stack trace ou logs relevantes
+- [ ] Componentes impactados
+
+#### Severidade e Prioridade (15%)
+
+- [ ] Severidade justificada (Crítico/Alto/Médio/Baixo)
+- [ ] Prioridade justificada
+- [ ] Impacto no usuário descrito
+- [ ] Quantidade de usuários afetados (se conhecido)
+
+#### Proposta de Solução (10%)
+
+- [ ] Solução proposta ou investigação necessária
+- [ ] Alternativas consideradas
+- [ ] Riscos da correção
+
+#### Testes de Regressão (5%)
+
+- [ ] Testes que devem ser criados
+- [ ] Áreas que devem ser testadas após correção
+- [ ] Cenários de regressão identificados
+
+---
+
+## Critérios Bloqueantes Automáticos
+
+Independente do score, o Quality Gate é **BLOQUEADO** se:
+
+| Tipo | Critério Ausente |
+|------|------------------|
+| **TASK** | Critérios de Aceitação |
+| **TASK** | Descrição vazia ou genérica |
+| **SPIKE** | Referências de Discovery |
+| **BUG** | Passos para Reproduzir |
+| **BUG** | Análise Técnica |
+
+---
+
+## Exemplos
+
+### Exemplo de Tech Spec Conforme (TASK)
+
+```markdown
+# TECH-001: Implementar Autenticação JWT
+
+## 1. Contexto da História
+
+**ID**: STORY-123
+**Link**: https://jira.empresa.com/browse/STORY-123
+
+**Como** usuário do sistema
+**Eu quero** fazer login com email e senha
+**Para que** eu possa acessar minhas informações de forma segura
+
+### Contexto de Negócio
+O sistema atual não possui autenticação. Usuários acessam sem identificação,
+o que impede personalização e rastreamento de ações.
+
+### Critérios de Aceitação (Produto)
+- Quando usuário insere credenciais válidas, então é redirecionado ao dashboard
+- Quando usuário insere credenciais inválidas, então vê mensagem de erro
+- Quando token expira, então usuário é redirecionado ao login
+
+### Escopo
+**Inclui:**
+- Login com email/senha
+- Geração de token JWT
+- Middleware de validação
+
+**Não Inclui:**
+- Login social (OAuth)
+- Recuperação de senha
+- 2FA
+
+## 2. Análise Técnica
+
+### Componentes Afetados
+| Componente | Tipo | Impacto |
+|------------|------|---------|
+| auth.service.ts | Criação | Alto |
+| user.controller.ts | Modificação | Médio |
+
+### Decisões Arquiteturais
+
+**Decisão 1: Armazenamento de Token**
+
+**Contexto**: Onde armazenar o token JWT no frontend?
+
+**Opções**:
+- Opção A: localStorage - Prós: simples. Contras: vulnerável a XSS
+- Opção B: httpOnly cookie - Prós: seguro. Contras: requer CSRF protection
+
+**Decisão**: httpOnly cookie
+**Justificativa**: Segurança é prioridade. CSRF é mitigável.
+
+## 3. Riscos e Mitigações
+
+| Risco | Prob. | Impacto | Mitigação | Plano B |
+|-------|-------|---------|-----------|---------|
+| Token vazado | Baixa | Alto | Expiração curta (1h) | Blacklist de tokens |
+```
+
+### Exemplo de Tech Spec Bloqueada (TASK)
+
+```markdown
+# Implementar Login
+
+## Descrição
+Fazer o login funcionar.
+
+## O que fazer
+- Criar tela de login
+- Conectar com backend
+```
+
+**Problemas**:
+- ❌ Sem TASK_MANAGER_KEY
+- ❌ Sem critérios de aceitação
+- ❌ Sem análise técnica
+- ❌ Sem decisões arquiteturais
+- ❌ Sem riscos mapeados
+
+**Status**: BLOQUEADO (0%)
+
+---
+
+## Referências
+
+- Template completo: `$IDE/templates/engineering/tech-spec-template.md`
+- Regras de Tech Spec: `$IDE/rules/engineering/eng.tech-spec-rules.md`