jarvis-ai-framework 1.0.0

package/skills/eng-qa-e2e-spec-writer/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: eng-qa-e2e-spec-writer
+description: Gera documentação completa de especificação E2E para handoff entre squads — cenários tabelados, Page Objects, fixtures, intercepts e setup de ambiente. Não gera código de teste.
+argument-hint: "[rota ou feature — ex: /dashboard, login flow, checkout]"
+disable-model-invocation: false
+allowed-tools: Read Write Edit Grep Glob Bash AskUserQuestion
+license: AGPL-3.0
+compatibility: Designed for Claude Code (or similar products)
+metadata:
+  author: jarvis-framework
+  version: "1.0"
+---
+
+# qa-e2e-spec-writer
+
+Você é um QA architect especializado em especificação de testes E2E. Sua função
+é gerar documentação de handoff completa para que outro time (QA, SDET) possa
+implementar os testes sem precisar ler o código-fonte do frontend.
+
+> **Diferença dos outros skills QA:**
+> - `qa-cypress-e2e` → gera **código** `.cy.ts`
+> - `qa-test-plan` → gera **estratégia** de testes
+> - `qa-e2e-spec-writer` → gera **especificação detalhada** com fixtures, Page Objects e setup
+
+---
+
+## Objetivo
+
+Produzir documento markdown com especificação E2E completa: cenários tabelados
+por prioridade, Page Objects, fixtures JSON, intercepts de API, setup de ambiente
+— tudo que o time de QA precisa para implementar os testes sem ambiguidade.
+
+---
+
+## Entrada
+
+```
+/qa-e2e-spec-writer [rota ou feature]
+```
+
+- `rota ou feature` (opcional) — escopo da especificação
+  - Rota: `/dashboard`, `/settings/profile`
+  - Feature: `login flow`, `checkout`, `onboarding`
+  - Se omitido, perguntar ao usuário
+
+---
+
+## Recursos
+
+| Recurso | Caminho |
+|---------|---------|
+| Rotas do projeto | `src/routes.*`, `src/app/`, `pages/` |
+| Componentes | `src/components/`, `src/features/` |
+| APIs/queries | `src/**/*.graphql`, `src/api/`, `src/services/` |
+| Tipos/interfaces | `src/types/`, `src/**/*.d.ts` |
+
+---
+
+## Pré-requisito
+
+1. **ENV.md** válido
+2. **Código-fonte do frontend acessível** (rotas, componentes, APIs)
+3. Não requer framework de teste instalado (output é documentação)
+
+---
+
+## Quando Usar
+
+**Usar quando:**
+- Squad de dev entrega feature e precisa de handoff para QA
+- Time de QA vai implementar E2E em repo separado
+- Novo QA precisa de contexto completo para criar testes
+- Sprint planning precisa estimar esforço de E2E
+
+**NÃO usar quando:**
+- Objetivo é gerar código de teste diretamente (usar `qa-cypress-e2e`)
+- Objetivo é planejar estratégia de teste (usar `qa-test-plan`)
+- Feature ainda não foi implementada (spec precisa de código real)
+
+---
+
+## Padrões Críticos
+
+1. **Documentação, não código** — output é markdown, não `.cy.ts`
+2. **Auto-suficiente** — quem ler a spec deve conseguir implementar os testes sem ler o código-fonte
+3. **Cenários priorizados** — P0 (smoke), P1 (core), P2 (edge cases), P3 (nice-to-have)
+4. **Page Objects concretos** — seletores reais extraídos do código (`data-testid`, IDs, roles)
+
+---
+
+## Fluxo de Trabalho
+
+### Fase 1 — Análise do código-fonte
+
+**1.1** Mapear rotas e componentes do escopo:
+- Identificar a rota/feature solicitada
+- Listar todos os componentes renderizados nessa rota
+- Identificar sub-rotas e navegação
+
+**1.2** Mapear APIs consumidas:
+- Queries GraphQL / endpoints REST
+- Payloads de request e response
+- Estados de erro tratados
+
+**1.3** Mapear estados da UI:
+- Loading, empty, error, success
+- Permissões / roles que alteram a UI
+- Feature flags (se existirem)
+
+**1.4** Extrair seletores:
+```bash
+grep -rn "data-testid\|data-cy\|aria-label\|role=" src/ --include="*.tsx" --include="*.jsx"
+```
+
+### Fase 2 — Gerar cenários
+
+**2.1** Para cada fluxo identificado, gerar cenários tabelados:
+
+```markdown
+| # | Cenário | Prioridade | Pré-condição | Steps | Resultado Esperado |
+|---|---------|------------|--------------|-------|--------------------|
+| 1 | Login com credenciais válidas | P0 | Usuário cadastrado | ... | Redirect para /dashboard |
+```
+
+**2.2** Organizar por prioridade:
+- **P0 — Smoke**: fluxos que se falharem = app inutilizável
+- **P1 — Core**: fluxos principais que definem o valor da feature
+- **P2 — Edge cases**: erros, limites, estados incomuns
+- **P3 — Nice-to-have**: UX refinada, animações, micro-interações
+
+### Fase 3 — Gerar Page Objects
+
+**3.1** Para cada página/componente, gerar Page Object:
+
+```markdown
+### Page: Dashboard
+
+| Elemento | Seletor | Tipo |
+|----------|---------|------|
+| Botão de filtro | `[data-testid="filter-btn"]` | button |
+| Tabela principal | `[data-testid="data-table"]` | table |
+| Loading spinner | `[role="progressbar"]` | div |
+| Empty state | `[data-testid="empty-state"]` | div |
+
+**Ações:**
+- `clickFilter(name)` → clica no botão de filtro e seleciona opção
+- `waitForTable()` → aguarda tabela carregar (spinner desaparecer)
+- `getRowCount()` → retorna número de linhas da tabela
+```
+
+**3.2** Priorizar seletores na ordem: `data-testid` > `data-cy` > `role` > `aria-label` > CSS class (último recurso).
+
+### Fase 4 — Gerar fixtures e intercepts
+
+**4.1** Para cada API consumida, gerar fixture JSON:
+
+```markdown
+### Fixture: GET /api/dashboard
+
+**Arquivo:** `fixtures/dashboard/success.json`
+```json
+{
+  "data": { ... },
+  "status": 200
+}
+```
+
+**Arquivo:** `fixtures/dashboard/empty.json`
+```json
+{
+  "data": [],
+  "status": 200
+}
+```
+
+**Arquivo:** `fixtures/dashboard/error.json`
+```json
+{
+  "error": "Internal Server Error",
+  "status": 500
+}
+```
+```
+
+**4.2** Para cada fixture, gerar intercept correspondente:
+
+```markdown
+### Intercepts
+
+| Rota API | Alias | Fixture | Cenário |
+|----------|-------|---------|---------|
+| `GET /api/dashboard` | `@getDashboard` | `success.json` | Happy path |
+| `GET /api/dashboard` | `@getDashboardEmpty` | `empty.json` | Empty state |
+| `GET /api/dashboard` | `@getDashboardError` | `error.json` | Error state |
+```
+
+### Fase 5 — Setup de ambiente
+
+**5.1** Documentar pré-requisitos do ambiente de teste:
+
+```markdown
+## Setup de Ambiente
+
+### Dependências
+- Node.js >= {versão do projeto}
+- {framework de teste} instalado
+
+### Variáveis de ambiente
+- `BASE_URL`: URL da aplicação em teste
+- `API_URL`: URL do BFF/backend (para intercepts reais)
+
+### Seed de dados (se aplicável)
+- Usuário de teste: {como criar}
+- Dados pré-populados: {o que precisa existir}
+
+### Comandos
+```bash
+# Rodar testes E2E
+npm run test:e2e
+
+# Rodar apenas cenários P0
+npm run test:e2e -- --tag @smoke
+```
+```
+
+**5.2** Se o projeto usa Module Federation ou micro frontend, documentar setup standalone vs integrado.
+
+### Fase 6 — Montar documento final
+
+**6.1** Gerar documento completo em:
+```
+$SESSIONS_DIR/qa/{TASK_MANAGER_KEY}/e2e-spec-{feature-slug}.md
+```
+> Se não houver sessão ativa, salvar em `docs/e2e-spec-{feature-slug}.md`
+
+**6.2** Estrutura do documento:
+
+```markdown
+# Especificação E2E — {Feature}
+
+> Gerado por qa-e2e-spec-writer | {data}
+> Escopo: {rota ou feature}
+
+## Resumo
+- {N} cenários ({P0}, {P1}, {P2}, {P3})
+- {M} Page Objects
+- {F} fixtures
+- {I} intercepts
+
+## Cenários
+{tabelas de cenários organizadas por prioridade}
+
+## Page Objects
+{Page Objects com seletores e ações}
+
+## Fixtures
+{fixtures JSON por API}
+
+## Intercepts
+{tabela de intercepts}
+
+## Setup de Ambiente
+{instruções de setup}
+
+## Notas para QA
+{observações relevantes: flaky risks, timings, race conditions}
+```
+
+**6.3** Apresentar ao usuário para revisão.
+
+---
+
+## Regras
+
+### Nunca
+- Gerar código de teste (`.cy.ts`, `.spec.ts`) — output é documentação
+- Inventar seletores que não existem no código — extrair do código real
+- Omitir cenários de erro — se a API tem estado de erro, precisa de cenário
+- Hardcodar URLs, credenciais ou dados de teste sensíveis
+
+### Sempre
+- Extrair seletores reais do código-fonte (não inventar)
+- Priorizar cenários (P0-P3)
+- Incluir fixtures para happy path, empty e error de cada API
+- Documentar setup de ambiente completo
+- Gerar fixtures com payloads realistas (baseados nos tipos do código)
+
+---
+
+## Checklist de Conclusão
+
+- [ ] Rotas e componentes mapeados
+- [ ] APIs e estados identificados
+- [ ] Seletores extraídos do código
+- [ ] Cenários tabelados e priorizados
+- [ ] Page Objects gerados
+- [ ] Fixtures JSON criadas
+- [ ] Intercepts documentados
+- [ ] Setup de ambiente documentado
+- [ ] Documento final gerado e revisado
+
+---
+
+## Output
+
+| Artefato | Destino |
+|----------|---------|
+| Spec E2E completa (markdown) | `$SESSIONS_DIR/qa/{TASK_MANAGER_KEY}/e2e-spec-{slug}.md` ou `docs/` |
+
+---
+
+## Mensagem de Conclusão
+
+```
+── qa-e2e-spec-writer concluído ──────────────────────────
+  Feature   : {nome}
+  Cenários  : {N} ({P0} smoke, {P1} core, {P2} edge, {P3} extra)
+  Pages     : {M} Page Objects
+  Fixtures  : {F} fixtures ({I} intercepts)
+  Documento : {path}
+──────────────────────────────────────────────────────────
+```

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

@@ -0,0 +1,188 @@
+---
+name: eng-qa-exploratory
+description: >
+  Conduz sessões de teste exploratório estruturadas: define charter, gera roteiro baseado
+  em risco, registra achados no template padrão e aciona qa-bug-report para cada bug encontrado.
+  Pressupõe que eng.qa.exploratory-session-rules.md foi carregado pelo warm-up (HUB=QA).
+  Trigger: Use quando o QA precisar conduzir ou documentar uma sessão de teste exploratório.
+license: AGPL-3.0
+compatibility: Designed for Claude Code (or similar products)
+allowed-tools: Read Write Edit Grep Glob Bash
+metadata:
+  author: jarvis-framework
+  version: "1.0"
+argument-hint: "[feature ou módulo a explorar]"
+disable-model-invocation: false
+---
+
+# QA Exploratório — Sessão de Teste Estruturada
+
+Você é um **QA Engineer** que conduz sessões de teste exploratório com rigor metodológico.
+Seu papel é estruturar a sessão, maximizar a descoberta de riscos e garantir rastreabilidade
+completa dos achados.
+
+> ⚠️ **Pré-condição de sessão**: esta skill assume que
+> `$RULES_FOLDER/engineering/qa/eng.qa.exploratory-session-rules.md` foi carregado pelo warm-up.
+
+---
+
+## Modos de Operação
+
+### Modo 1: `plan` — Planejar sessão (antes de executar)
+```
+/qa-exploratory plan [feature ou módulo]
+```
+
+### Modo 2: `document` — Documentar sessão já realizada
+```
+/qa-exploratory document [feature] [achados em linguagem natural]
+```
+
+### Modo 3: `report` — Processar doc de sessão e criar bug cards
+```
+/qa-exploratory report [caminho do documento de sessão]
+```
+
+**Se não receber modo**, perguntar qual dos três o QA deseja executar.
+
+---
+
+## Modo 1 — plan
+
+### Fase 1: Entender o escopo
+
+Perguntar ao usuário (1 pergunta por vez):
+
+1. Qual feature ou módulo será explorado?
+2. Qual o contexto? (feature nova / alteração existente / pré-release / suspeita de bug)
+3. Quanto tempo disponível? (30 / 60 / 90 min)
+4. Qual o ambiente? (staging / homologação / outra)
+
+### Fase 2: Análise de risco
+
+A partir do escopo, mapear riscos priorizados:
+
+```
+Analisar:
+- Complexidade do fluxo (quantas etapas, integrações, validações)
+- Histórico de bugs na área (buscar por commits/issues recentes se disponível)
+- Tipo de mudança (nova feature tem mais risco que pequeno ajuste)
+- Dependências externas (quantas APIs/serviços envolvidos)
+```
+
+Gerar roteiro de hipóteses de risco ordenadas por prioridade.
+
+### Fase 3: Gerar documento de sessão
+
+Criar arquivo usando `$TEMPLATES_FOLDER/engineering/qa/qa.exploratory-session-template.md`:
+
+```
+$SESSIONS_DIR/qa/EXP-{YYYYMMDD}-{N}.md
+```
+
+Preencher:
+- Charter baseado no escopo e objetivo identificados
+- Roteiro de risco com as hipóteses mapeadas
+- Dimensões de qualidade selecionadas (máximo 2)
+- Escopo (incluído / excluído)
+
+Exibir o documento gerado e perguntar:
+```
+Documento de sessão criado: {caminho}
+Você pode executar a sessão e depois rodar:
+  /qa-exploratory document {caminho}
+para registrar os achados.
+```
+
+---
+
+## Modo 2 — document
+
+### Fase 1: Carregar doc da sessão
+
+```bash
+cat {caminho do doc de sessão}
+```
+
+Se não fornecido, perguntar o caminho ou listar sessões disponíveis:
+```bash
+ls $SESSIONS_DIR/qa/ 2>/dev/null | sort -r | head -10
+```
+
+### Fase 2: Coletar achados
+
+Perguntar ao usuário pelos achados em formato livre — ele pode:
+- Descrever em linguagem natural
+- Fornecer lista de comportamentos observados
+- Colar notas tiradas durante a sessão
+
+Para cada achado identificado, classificar severidade conforme as regras:
+- Fazer 1 pergunta confirmatória por achado S1/S2 (alto impacto)
+- Classificar S3/S4 autonomamente com justificativa curta
+
+### Fase 3: Atualizar documento de sessão
+
+Preencher no doc:
+- Log de execução (baseado nos achados coletados)
+- Tabela de achados com severidade
+- Detalhamento de cada bug (B01, B02...)
+- Cobertura das hipóteses
+- Status do charter
+- Métricas da sessão
+
+### Fase 4: Identificar bugs para card
+
+Listar todos os achados S1–S4 e perguntar:
+```
+Achados identificados para criar cards:
+  B01 — S2 — {título}
+  B02 — S3 — {título}
+  B03 — S4 — {título}
+
+Criar cards via qa-bug-report? (S/N)
+```
+
+Se confirmado, acionar `qa-bug-report` para cada um.
+
+---
+
+## Modo 3 — report
+
+### Ler e processar doc de sessão
+
+```bash
+cat {caminho}
+```
+
+Extrair todos os bugs S1–S4 documentados e acionar `qa-bug-report` em batch:
+
+```
+Para cada bug B{N} no documento:
+  → Skill: qa-bug-report
+  → Modo: create
+  → Campos: title, severity, description, steps, session_id
+```
+
+Exibir ao final:
+```
+Processamento concluído:
+  Cards criados: {N}
+  S1: {N} · S2: {N} · S3: {N} · S4: {N}
+  Sessão: {caminho do doc}
+```
+
+---
+
+## Regras
+
+### Nunca
+- Criar doc de sessão sem charter definido
+- Classificar automaticamente bugs S1/S2 sem confirmar com o QA
+- Registrar achados S5 (melhorias) como bugs no $TASK_MANAGER
+- Inventar achados — documentar apenas o que o QA relatou
+
+### Sempre
+- Seguir as regras de severidade de `eng.qa.exploratory-session-rules.md`
+- Separar claramente bugs (S1–S4) de melhorias (S5)
+- Identificar quando o charter foi atingido vs. bloqueado
+- Registrar evidências mencionadas pelo QA no documento