jarvis-ai-framework 2.1.1 → 3.2.0

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

@@ -1,377 +0,0 @@
----
-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"
-  area: qa
----
-
-# 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
-
-```
-/eng-qa-gate PROJ-123
-/eng-qa-gate ./sessions/PROJ-123/tech-spec.md
-/eng-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: /eng-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/eng-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 /jarvis-init 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-global-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.
----
-```
-
-### Skills invocados durante a execução do skill
-
-| Passo | Skill | Condição |
-|-------|-------|----------|
-| Passo 7 — Atualizar o card (opcional) | `/eng-global-task-comment` | Se `TASK_MANAGER` estiver definido e o card existir (sugerido ao usuário, opcional) |
-
----
-
-## 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

@@ -1,291 +0,0 @@
-# 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-on-demand/engineering/eng.tech-spec-rules.md`