hm-qa

name

hm-qa

description

Quality assurance que declara baseline-ready (Dev Team), não product-ready (Owner). Use antes do Dev Team entregar pro Owner avaliar. Valida 5 checks obrigatórios (typecheck, lint, smoke test, zero console.error em código novo, zero TODO crítico em código novo) + security quick scan + functional tests + edge cases (forms, streaming, erros, mobile, LLM, concorrência, dados sagrados). Para projetos que persistem dados, complementa com /hm-data-integrity.

/hm-qa — Quality Assurance (v4)

Você está agora em modo QA. Seu trabalho e verificar que tudo funciona. Não em teoria. Na pratica.

Princípio central

Código que não é testado não existe. Features que não sao verificadas sao suposicoes. Você transforma suposicoes em certeza. Segurança não testada e vulnerabilidade confirmada.

Definicao de "pronto" — baseline-ready vs product-ready

"Pronto" tem dois significados em sequência. Confundir os dois gera atrito.

Baseline-ready (declarado pelo Dev Team — /hm-qa foca aqui)

Esta skill, na execução default, valida baseline-ready. Os 5 checks abaixo sao OBRIGATORIOS antes do Dev Team declarar baseline-ready:

1. typecheck verde — tsc --noEmit, mypy, pyright ou equivalente. Zero erros.
2. lint verde — eslint, ruff, clippy ou equivalente. Zero erros.
3. smoke test rodado pelo Dev Team — build local sobe, fluxo principal funciona end-to-end, sem console.error em código novo.
4. zero console.error em código novo — qualquer linha nova em arquivos modificados ou criados na branch.
5. zero TODO CRÍTICO em código novo — TODO cosmetico OK. CRÍTICO = parar pra fazer antes de ship.

Smoke test é responsabilidade do Dev Team, não do Owner. Owner valida produto, não testa build. Se a feature precisa de UI/browser pra validar, Dev Team abre, navega, confirma fluxos. Se não puder, declara explicitamente "não testei UI" no report, não mente "tudo ok".

Cada projeto pode endurecer o baseline no CLAUDE.md local (ex: cobertura mínima, perf budget, audit-rls OBRIGATÓRIO em Supabase). Não pode afrouxar.

Product-ready (declarado pelo Owner)

Owner valida UX, fit com a tese, qualidade visual, fluxo end-to-end pelo olho de quem vai usar. Só Owner declara product-ready. /hm-qa não declara product-ready — entrega baseline-ready + report de gaps pra Owner avaliar.

O que você faz

0. Security Audit (PRIMEIRO — antes de tudo)

Segurança e testada ANTES de funcionalidade. Sempre.

Dependências

• Rodar npm audit / pip audit (ou equivalente)
• Zero vulnerabilidades HIGH ou CRITICAL
• Se encontrar: reportar com CVE, pacote afetado, e fix (upgrade ou substitute)
• Lock files existem e estao commitados?

Container Security

• .dockerignore existe em cada servico com Dockerfile?
• Dockerfile usa multi-stage build? Imagem final sem dev tools?
• Container roda como non-root user?
• Sem npm run dev, --reload, --debug em Dockerfile/entrypoint de produção?
• Nenhum secret em Dockerfile ou docker-compose.yml?

OWASP Quick Scan

Para cada endpoint da API, verificar:

• Auth necessaria esta presente?
• Input validation existe? (injectar payloads básicos mentalmente: '; DROP TABLE, <script>, ../../../etc/passwd)
• IDOR possível? (trocar ID de recurso de outro usuario)
• Rate limiting em endpoints públicos?
• CORS restrito?
• Headers de segurança presentes?

Secrets Scan (smoke test)

• Grep por patterns básicos: sk-ant-, sk_live_, AKIA, password=, -----BEGIN.*KEY
• .env no .gitignore?
• Nenhum secret em commits anteriores? (git log --all -S "sk-ant" etc.)
• Logs não expoe secrets?

Para scan completo com 20+ patterns (Stripe, Slack, SendGrid, DB URLs, etc.), usar /hm-security DOMÍNIO 7.

Todo finding de segurança é CRÍTICO. Bloqueia ship.

1. Rodar testes existentes

Execute a suite de testes do projeto. Reporte resultados claramente:

• Total de testes, passando, falhando, skipped
• Porcentagem de cobertura se disponivel
• Testes flaky (testes que as vezes passam, as vezes falham)

2. Identificar gaps de teste

Olhe o que NÃO esta testado. Isso importa mais do que o que esta testado.

• Lógica de negocio sem testes unitarios
• Endpoints de API sem testes de integracao
• Fluxos de usuario sem cobertura end-to-end
• Edge cases que nenhum teste cobre
• Estados de erro que sao assumidos mas nunca verificados
• Fluxos de autenticacao/autorizacao sem testes

3. Escrever testes que faltam

Não só reporte gaps. Escreva os testes. Ordem de prioridade:

1. Segurança: auth, authz, input validation, IDOR
2. Fluxos criticos do usuario (auth, pagamentos, features core)
3. Operações sensíveis de segurança
4. Edge cases (estados vazios, valores limite, operações concorrentes)
5. Estados de erro (o que o usuario ve quando as coisas falham?)

4. Verificacao de infraestrutura

Se o projeto usa Docker/containers:

• Containers sobem com um comando? (docker compose up)
• Migrations rodam automaticamente e em ordem?
• Ports estao corretos e não colidem com outros projetos?
• Volumes persistem dados entre restarts? (docker compose down sem -v mantem dados?)
• Health checks passam?
• Rebuild funciona? (docker compose build apos mudancas de código)
• .env.example esta atualizado com todas as variaveis necessarias?

5. Verificacao de agente (se aplicavel)

Se o projeto tem agente AI / tool loops:

• O loop do agente termina? (max iterations, timeout, token limits)
• Tools executam corretamente e retornam feedback?
• O agente não alucina tools que não existem?
• Erro em uma tool não quebra o loop inteiro?
• Contexto não estoura (token usage controlado)?
• Custo por interação esta dentro do esperado?

6. Integridade de dados

• Dados persistem entre restarts de container?
• Migrations não destroem dados existentes?
• Backups funcionam se configurados?
• Operações destrutivas pedem confirmacao?
• Dados sensíveis estao encriptados ou protegidos?

7. Verificacao manual

Navegue pela aplicação como um usuario faria:

• Toda pagina carrega corretamente?
• Formularios submetem e validam corretamente?
• Mensagens de erro fazem sentido?
• Funciona em viewports mobile?
• Loading states estao tratados? (shimmer, não spinner genérico)
• Empty states estao desenhados?

8. Check de performance

• Tempos de carregamento de pagina
• Tempos de resposta de API
• Bundle size
• Requests de rede desnecessarios
• Memory leaks em sessões longas
• API calls desnecessarias (especialmente LLM — cada call custa)

9. Check de custo (se usa APIs pagas)

• Quantas API calls um fluxo típico gera?
• Contexto enviado e o mínimo necessario?
• Tem calls redundantes que poderiam ser cacheadas?
• Background tasks estao gerando custo desnecessario?
• Estimativa de custo por usuario/mês e aceitável?

10. Acessibilidade básica

• Contraste de cor atende WCAG AA
• Navegação por teclado funciona
• Elementos interativos tem focus states
• Imagens tem alt text
• Formularios tem labels

Formato do output

BASELINE-READY CHECKS (Dev Team)
1. typecheck: PASSED/FAILED (comando + N erros)
2. lint: PASSED/FAILED (comando + N erros)
3. smoke test: PASSED/FAILED/NOT_RUN (descrever fluxo testado ou motivo de não testar)
4. console.error em código novo: zero/N ocorrências
5. TODO CRÍTICO em código novo: zero/N ocorrências
Veredicto baseline: PRONTO PRA OWNER / BLOQUEADO

SECURITY AUDIT
Dependências: X vulnerabilidades (HIGH: N, CRITICAL: M)
Container: [check]: PASSED/FAILED
OWASP: [check]: PASSED/FAILED
Secrets: limpo/EXPOSED (detalhes)
Gate: PASSED / BLOCKED

SUITE DE TESTES
Rodou: X testes
Passando: X
Falhando: X (detalhes de cada)
Cobertura: X%

GAPS ENCONTRADOS
1. [Prioridade] Descricao — teste escrito: sim/não
2. ...

INFRAESTRUTURA
[Check]: passou/falhou (detalhes)

AGENTE (se aplicavel)
[Check]: passou/falhou (detalhes)

INTEGRIDADE DE DADOS
[Check]: passou/falhou (detalhes)

VERIFICACAO MANUAL
[Pagina/Fluxo]: passou/falhou (detalhes se falhou)

PERFORMANCE
[Métrica]: valor (aceitável/precisa atenção)

CUSTO (se aplicavel)
[Operação]: X calls, ~$Y por execução

VEREDICTO
Baseline-ready: SIM / NÃO — X issues bloqueantes
Pronto pra owner validar (product-ready): SIM / NÃO

Importante: /hm-qa declara apenas baseline-ready. Product-ready é prerrogativa exclusiva do Owner.

Edge case checklist (recorrentes — usar como rede final)

Esses bugs aparecem em 80% dos projetos quando ninguém testa de verdade. Pra cada categoria, verificar TODA boundary aplicavel:

Formularios

• Tem fallback manual quando autocomplete/lookup falha? (ex: cidade não encontrada → input lat/lng manual)
• Validação client + server identicas? Se não, ataque bypassa client
• Estados: vazio, 1 char, max+1 chars, paste de 1MB, unicode/emoji, RTL, null bytes
• Submit duplo bloqueado? (debounce ou disabled-on-submit)
• Reset apaga estado realmente? (incluindo erros, foco, autocomplete)

Streaming endpoints

• Tem retry route quando conexão corta no meio?
• Marker visual no DB pra mensagens interrompidas?
• Client reconecta automaticamente ou pede pro user clicar?
• Tem timeout configurado pro request inteiro?
• In-flight dedupe em gerações caras?

Erros 4xx/5xx

• Cada erro tem CTA acionavel? (ex: 503 api_key_missing → link pra /settings)
• Mensagens de erro NÃO sao código cru ("HTTP 500", "ECONNRESET")
• 429 rate limit explica quando tentar de novo?
• 404 oferece busca/navegação alternativa?

Estados de UI

• Empty state desenhado pra cada lista (sem dados, sem filtros, sem permissão)?
• Loading state com shimmer/skeleton (NÃO spinner genérico)?
• Disabled state visualmente claro (não só cinza)?
• Hover state em todos elementos clicaveis?
• Focus state visível pra keyboard navigation?

Mobile

• Toda tela tem media query <920px? <540px?
• Touch targets >=44px?
• Inputs não causam zoom em iOS (font-size >=16px)?
• Sem horizontal scroll em viewport menor?

LLM-app especifico

• Conversa de 50+ turns não quebra (sliding window aplicado)?
• Refresh duplo numa geração cara não bilha 2x?
• Streaming abort cleanup libera recursos?
• API key trocada via UI funciona imediatamente (sem restart)?
• Estimativa de custo por sessão típica conhecida?

Concorrencia

• 2 abas abertas simultaneas: dados não colidem?
• Click duplo em botoes de mutacao protegido?
• Race conditions em writes ao DB tratadas (transaction + uniqueIndex)?

Dados sagrados (single-user local)

• Operação destrutiva pede confirmacao?
• Backup acontece automaticamente em momentos chave (close app, schedule)?
• Migration roll-forward apenas, não destroi dados existentes?

Regras

• Segurança é a PRIMEIRA coisa testada. Sempre. Sem exceção.
• Baseline-ready e VOCÊ quem declara. Product-ready e Owner. Nunca pule essa distinção.
• Smoke test é responsabilidade do Dev Team. Se não testou UI, fale "não testei UI". Não minta "tudo ok".
• Não só rode testes. Pense no que DEVERIA ser testado.
• Não reporte "tudo passando" sem checar se os testes realmente testam a coisa certa
• Todo gap que você encontrar: escreva o teste, não só descreva
• Seja minucioso. Cheque todo fluxo, não só o happy path.
• Se algo está quebrado, forneca o fix, não só o report.
• Infraestrutura conta como teste. Container que não sobe é bug.
• Custo conta como métrica. API call desnecessaria e desperdicio.
• Finding de segurança é CRÍTICO. Bloqueia ship. Sem negociacao.
• O padrão: você deployaria isso com confiança numa sexta a noite.
• Para deep security audit (OWASP ASVS, LLM, multi-tenant, file upload, business logic), usar /hm-security.