agent-engineering-skills 1.0.0

package/skills/audit/state-consistency-audit/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: state-consistency-audit
+description: Compares state across database, API, server state, cache, client state, and URL state, and looks for divergences where the layers disagree about what is true.
+category: audit
+triggers:
+  - "audit state consistency"
+  - "find cache and database divergence"
+  - "client and server state out of sync"
+  - "url state vs server state"
+  - "stale cache bugs"
+priority: high
+---
+
+# State Consistency Audit
+
+## Objective
+
+Ensinar o agente a tratar o "estado do sistema" não como uma coisa única, mas como
+**várias cópias que devem concordar** — e a procurar os pontos onde elas divergem.
+
+```text
+database   API response   server (in-memory)   cache   client state   URL state
+```
+
+Um bug de consistência acontece quando duas camadas afirmam coisas diferentes sobre o
+messe fato (ex: cache diz "saldo 100", banco diz "50") e o sistema age sobre a errada.
+
+## When to Use
+
+* Quando o sistema tem cache (CDN, Redis, in-memory, SWR/React Query no cliente).
+* Quando o estado é refletido na URL (filtros, paginação, tabs, modais via querystring).
+* Quando o cliente mantém estado (otimistic UI, estado local vs servidor).
+* Quando há read replicas, eventual consistency, ou mensagens assíncronas.
+* Quando o pedido menciona "stale", "out of sync", "cache", "refresh shows wrong",
+  "desync".
+* **Composição:** pareia com `user-flow-audit` (refresh/back-button causam desync),
+  `data-integrity-audit` (o banco como fonte de verdade), `error-flow-audit` (estado
+  parcial após falha), `edge-case-hunter` (stale data como edge).
+
+## Mental Model
+
+O "estado" não é uma variável — é um **conjunto de representações** que o sistema
+mantém em diferentes latências e locais por performance/UX. Cada representação tem um
+TTL, um caminho de invalidação, e um caminho de leitura. Bugs nascem quando:
+
+1. **Invalidação ausente** — o estado muda no banco mas o cache não é invalidado.
+2. **Ordem de invalidação errada** — escreve no cache antes do banco (e falha), ou
+   invalida depois de servir a leitura stale.
+3. **Otimistic UI não revertida** — o cliente assume sucesso, atualiza a UI, o servidor
+   falha, a UI fica inconsistente com o servidor.
+4. **URL como fonte de verdade sem servidor** — a URL diz um estado que o servidor não
+   conhece (deep link para estado que expirou/foi revogado).
+5. **Read replica lag** — escreve no primário, lê da replica antes da replicação, vê
+   estado antigo.
+
+A pergunta central para cada fato do sistema: **qual camada é a fonte de verdade, e
+todas as outras convergiram para ela?**
+
+## Investigation Procedure
+
+1. **Inventariar as camadas de estado** para o componente/fluxo. Nem todos os fluxos
+   usam todas as seis; liste só as que existem.
+2. **Para cada fato relevante** (saldo, status do recurso, permissão, contador), rotule
+   a **fonte de verdade** (geralmente o banco) e as **cópias** (cache, cliente, URL).
+3. **Traçar o caminho de escrita** — onde o fato é mutado, e em que ordem as camadas
+   são atualizadas.
+4. **Traçar o caminho de leitura** — qual camada é lida em cada ponto, e se há fallback.
+5. **Procurar invalidação ausente ou tardia** — quando o fato muda, cada cópia é
+   invalidada/atualizada? Antes ou depois de servir leituras?
+6. **Testar desyncs concretos:**
+   * Mutar + ler imediatamente de cache (stale read).
+   * Mutar no primário + ler de replica (lag).
+   * Otimistic update + falha de servidor (UI não revertida).
+   * Deep link via URL para estado revogado (URL ≠ servidor).
+   * Duas abas / dois clientes mutando (um vê estado do outro?).
+7. **Confirmar com evidência** — mostre as duas camadas discordando.
+8. **Reportar** via `templates/audit-report.md`.
+
+## Questions to Ask
+
+* Quais camadas de estado existem neste fluxo? Qual é a fonte de verdade?
+* Quando o fato muda no banco, o cache é invalidado? Quando — antes ou depois de servir?
+* Há read replicas? A leitura após escrita vai para a replica ou o primário?
+* A UI atualiza otimisticamente? Se o servidor falha, a UI reverte?
+* A URL reflete estado? Esse estado é validado contra o servidor no carregamento?
+* Dois clientes (duas abas, dois dispositivos) mutam o mesmo recurso — um vê a mudança
+  do outro? Quando?
+* Há TTL de cache maior que a janela de mutação esperada?
+* O cache é populado por quem? E invalidado por quem? (populador ≠ invalidador = bug)
+
+## Attack Patterns
+
+```text
+stale cache read
+    write db: balance 50 (was 100)
+    read cache: balance 100        ← invalidação faltou ou é assíncrona
+    → age sobre 100, permite gastar além do real
+
+read replica lag
+    write primary: status "paid"
+    read replica (imediatamente): status "pending"   ← replicação não convergiu
+    → trata como pendente, reprocessa, duplica efeito
+
+optimistic UI not reverted
+    user clicks "like" → UI: liked ✓ (optimistic)
+    server: 401/500                   ← falha
+    UI permanece liked ✓              ← não reverteu
+    → UI ≠ servidor
+
+URL ≠ server state
+    url: /doc/123?mode=edit
+    server: doc 123 was deleted / permission revoked
+    → carrega modo edit de recurso inacessível?
+
+two-client divergence
+    client A: edits resource, saves → server updated
+    client B: still showing old version (no realtime/poll)
+    → B edita sobre estado antigo, sobrescreve A
+
+cache populated by A, invalidated by nobody
+    service A writes cache on read (populate-on-miss)
+    service B writes db directly, never invalidates cache
+    → cache perpetuamente stale até TTL
+
+in-memory server state across instances
+    instance 1: local cache of "rate limit count"
+    instance 2: separate local cache
+    → limit bypassable by rotating instance (round-robin)
+```
+
+## Evidence Requirements
+
+* **Nomear as duas camadas que discordam** e o fato específico.
+* **Mostrar o estado em cada camada** (valor no banco vs valor no cache/cliente/URL).
+* **Mostrar o mecanismo da divergência** — qual caminho de escrita não invalidou, qual
+  lag, qual otimistic não revertido.
+* **Escalar confiança:**
+  * `CONFIRMED` — reproduziu e capturou os dois valores discordando (ex: resposta da
+    API vs query no banco).
+  * `HIGH CONFIDENCE` — código mostra invalidação ausente ou ordem errada, sem
+    reprodução manual.
+  * `POSSIBLE` — caminho plausível de desync, não confirmado.
+  * `SPECULATIVE` — "pode ficar stale" sem rastrear o mecanismo.
+* Desyncs que permitem **agir sobre estado errado** (gastar saldo stale) são mais
+  graves que desyncs puramente visuais.
+
+## False Positives
+
+* **Stale visual aceitável** — alguns caches são *desenhados* para ser stale (ex:
+  contagem de likes aproximada, eventual consistency por produto). Se o sistema
+  tolera stale por design, não é bug. Marcar `POSSIBLE` e levantar como decisão de
+  produto se duvidar.
+* **Invalidação existe mas é assíncrona por design** — invalidação eventual dentro de
+  uma janela documentada é aceitável; bug é só se a janela é indefinida ou não
+  garantida.
+* **URL é puramente de UI** — se a URL só controla view state (tab aberta) sem claims
+  sobre dados, "URL ≠ servidor" não aplica.
+* **Optimistic revert existe** — se há rollback no `onError`, não reportar. Confirmar
+  a ausência antes.
+* **Read replica com read-your-writes guarantee** — se a leitura pós-escrita vai ao
+  primário (ou replica com lag < janela crítica), lag não é problema.
+
+## Output Format
+
+Para cada par de camadas que discorda com consequência, um finding via
+`templates/audit-report.md`. Em **Affected component**, nomeie as camadas e o fato. Em
+**Reproduction**, mostre a sequência (write → read) que produz a divergência e os dois
+valores observados. Em **Root cause**, diga qual invalidação/ordem/lag/revert falta.
+Em **Recommendation**, indique a estratégia (write-through, invalidação síncrona,
+read-your-writes para o primário, rollback de optimistic, validação de URL no load).
+
+Apresente um mapa de camadas por fato (fato | fonte de verdade | cópias | caminho de
+invalidação | ✓/✗), marcando os desyncs. Desyncs que permitem agir sobre estado errado
+primeiro; desyncs visuais depois.

package/skills/audit/user-flow-audit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: user-flow-audit
+description: Maps a user flow as entry → preconditions → action → state change → feedback → next state and detects dead ends, impossible states, skippable steps, refresh and back-button problems, and duplicate operations.
+category: audit
+triggers:
+  - "audit a user flow"
+  - "map the states of a feature"
+  - "find dead ends in a flow"
+  - "review onboarding or checkout flow"
+  - "what happens on refresh or back button"
+priority: high
+---
+
+# User Flow Audit
+
+## Objective
+
+Ensinar o agente a modelar um fluxo de usuário como uma **máquina de estados** e a
+procurar estados dos quais o usuário não consegue sair, estados impossíveis, passos que
+podem ser pulados, e desyncs causados por refresh/back-button.
+
+A skill trata o fluxo como uma sequência canônica:
+
+```text
+entry → preconditions → action → state change → feedback → next state
+```
+
+## When to Use
+
+* Ao auditar qualquer fluxo multi-passo (onboarding, checkout, criação de personagem,
+  publicação, convites, setup).
+* Quando o pedido menciona "flow", "steps", "wizard", "onboarding", "checkout".
+* Quando há risco de o usuário ficar preso em um estado intermediário.
+* **Composição:** frequentemente junto com `state-consistency-audit` (fluxo vs estado
+  do servidor), `error-flow-audit` (o que acontece quando um passo do fluxo falha),
+  `business-logic-audit` (pré-condições do fluxo = regras de negócio), e
+  `edge-case-hunter` (entrances anômalas no fluxo).
+
+## Mental Model
+
+Um fluxo não é uma lista de telas. É uma **máquina de estados**: cada nó é um estado
+persistido (no servidor, no cliente, ou na URL), e cada transição é uma ação que move
+de um estado a outro. Bugs vivem nas transições e nos estados, não nas telas.
+
+As duas falhas mais comuns:
+
+1. **Estados sem saída** — o usuário chega a um estado do qual nenhuma ação legítima o
+   tira. Dead end.
+2. **Transições implícitas** — o fluxo assume que o estado anterior foi atingido, mas
+   nada o impede de pular direto a um estado posterior. Passo pulável.
+
+O modelo força a pergunta: *de cada estado, para onde o usuário pode ir — e o que o
+impede de ir para onde não deveria?*
+
+## Investigation Procedure
+
+1. **Desenhar o fluxo nominal** como `entry → preconditions → action → state change →
+   feedback → next state`. Um nó por estado.
+2. **Rotular onde cada estado vive** — servidor, cliente, URL, ou cache. (Isto
+   conecta com `state-consistency-audit`.)
+3. **Para cada transição, listar a pré-condição** que deve ser verdadeira para ela
+   ocorrer.
+4. **Testar pulabilidade:** a pré-condição é *verificada no servidor* ou *assumida*? Se
+   assumida, o passo é pulável via chamada direta ao endpoint do passo seguinte.
+5. **Testar estados sem saída:** para cada estado, existe uma ação legítima que leva a
+   um próximo estado útil? Se não, é dead end.
+6. **Testar refresh:** em cada estado, o que acontece se o usuário recarregar? O estado
+   é reconstruído a partir do servidor, ou perdido/resetado?
+7. **Testar back-button:** o que acontece ao voltar? O usuário reexecuta uma ação
+   não-idempotente? Volta a um estado que não deveria mais ser acessível?
+8. **Testar duplicação:** o usuário pode executar a mesma ação duas vezes (duplo submit,
+   double click) e causar dois efeitos?
+9. **Listar estados impossíveis** — combinações que a máquina deveria proibir mas que
+   podem ser alcançadas por pulo, refresh, ou back.
+10. **Reportar** findings via `templates/audit-report.md`.
+
+## Questions to Ask
+
+* Quais são todos os estados do fluxo? Onde cada um é persistido?
+* Para cada transição, qual a pré-condição? Ela é checada no servidor?
+* Existe um estado do qual nenhuma ação leva a lugar útil? (dead end)
+* Posso pular direto para um estado avançado sem passar pelos anteriores?
+* O que o refresh faz em cada estado? O estado é recuperado do servidor ou perdido?
+* O back-button reexecuta uma ação? Volta a um estado obsoleto?
+* Um duplo-submit cria dois recursos / duas recompensas?
+* Existem combinações de estado que deveriam ser impossíveis mas são alcançáveis?
+* O feedback dado ao usuário reflete o estado real do servidor?
+
+## Attack Patterns
+
+```text
+skip preconditions
+    POST /step-final     (pulando /step-1 e /step-2)
+    → efeito concedido sem pré-condições?
+
+dead end
+    state: "payment_failed"
+    → existe botão "retry"? "cancel"? ou o usuário fica preso?
+
+refresh mid-flow
+    state: "form partially submitted"
+    refresh → estado reconstruído? ou volta ao início perdendo dados?
+
+back-button after submit
+    submit → state: "created"
+    back → volta ao form → submit novamente
+    → criação duplicada?
+
+duplicate operation
+    double click em "Submit"
+    → dois requests, dois efeitos?
+
+impossible state reachable
+    resource marcado "deleted" mas ainda listado e editável
+    → combinação proibida alcançada por caminho indireto
+
+stale feedback
+    UI mostra "success" mas servidor reverteu por erro interno
+    → feedback ≠ estado real
+```
+
+## Evidence Requirements
+
+* **Nomear o estado e a transição** problemáticos (ex: "do estado `submitted` via
+  back-button de volta a `form`").
+* **Mostrar onde o estado vive** (server/client/URL/cache) e onde a pré-condição é (ou
+  não é) verificada.
+* **Reproduzir ou apontar o mecanismo** — sequência de passos/requests, ou o código que
+  assume a pré-condição sem checá-la.
+* **Escalar confiança:**
+  * `CONFIRMED` — reproduziu o dead end / o pulo / o desync.
+  * `HIGH CONFIDENCE` — mecanismo claro no código (ex: handler não checa etapa
+    anterior), sem reprodução manual.
+  * `POSSIBLE` — fluxo parece permitir, caminho plausível, não confirmado.
+  * `SPECULATIVE` — "acho que refresh pode quebrar" sem rastrear o mecanismo.
+
+## False Positives
+
+* **Pré-condição verificada no servidor** — se o handler do passo final valida que os
+  anteriores ocorreram, o "pulo" não produz efeito. Confirmar antes de reportar.
+* **Estado é puramente de UI** — alguns estados "intermediários" são só feedback visual
+  sem estado persistido; "perdê-los" no refresh é aceitável se o servidor é a verdade.
+* **Back-button em fluxo idempotente** — se reexecutar é seguro (idempotência real),
+  não é bug (relacionado a `idempotency-audit`).
+* **Dead end é intencional** — alguns estados terminais são deliberados (ex: "conta
+  banida"). Reportar como tal, não como defeito, ou marcar como `POSSIBLE` para decisão
+  de produto.
+* **Duplicação protegida por disable de botão + server idempotency** — defesa em
+  profundidade; se ambas existem, não reportar.
+
+## Output Format
+
+Para cada estado/transição problemática, um finding via
+`templates/audit-report.md`. Em **Reproduction**, dê a sequência exata de estados
+visitados (incluindo refresh/back) que leva ao defeito. Em **Affected flow**, nomeie o
+fluxo. Em **Recommendation**, indique *onde* corrigir (validação server-side no handler
+do passo final; bloqueio de estado obsoleto; reconstrução de estado no refresh).
+
+Anexe um diagrama da máquina de estados com os estados/transições problemáticos
+marcados. Estados sem saída e transições puláveis são os mais graves — liste-os
+primeiro.

package/skills/frontend/accessibility-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: accessibility-review
+description: Evaluates keyboard navigation, screen readers, focus management, semantic HTML, contrast, touch targets, reduced motion, forms, and error handling against WCAG standards.
+category: frontend
+triggers:
+  - "audit accessibility"
+  - "check keyboard navigation"
+  - "review screen reader support"
+  - "semantic html and aria"
+  - "wcag compliance"
+  - "touch targets and focus"
+  - "reduced motion and forms"
+priority: high
+---
+
+# Accessibility Review
+
+## Objective
+
+Ensinar o agente a avaliar uma interface contra padrões de acessibilidade (WCAG):
+keyboard, screen readers, focus, semantic HTML, contrast, touch targets, reduced
+motion, forms, e erros. Como define o `plan.md` §10: acessibilidade não é extra — é
+parte da definição de qualidade.
+
+## When to Use
+
+* Em qualquer tela que será usada por pessoas reais.
+* Antes de lançar features que envolvem formulários, navegação, modal, interação
+  complexa, ou conteúdo dinâmico.
+* Quando o pedido menciona "accessibility", "a11y", "WCAG", "keyboard", "screen
+  reader", "aria", "focus", "contrast", "touch target", "reduced motion".
+* **Composição:** roda com todas as frontend skills. Pareia especialmente com
+  `interaction-design` (focus, keyboard, feedback), `animation-review` (reduced
+  motion), `ux-review` (clareza, erro, feedback), e `visual-quality-review` (contrast).
+
+## Mental Model
+
+Acessibilidade não é sobre "adicionar ARIA". É sobre **garantir que o sistema funciona
+independente de como o usuário acessa**. A regra prática: se uma funcionalidade não
+funciona só com teclado, ou se o conteúdo não é legível por um screen reader, a
+funcionalidade está quebrada para uma parcela dos usuários.
+
+Eixos (do `plan.md` §10):
+
+```text
+keyboard         — cada ação é alcançável com Tab/Enter/Esc (sem mouse trap)
+screen readers   — conteúdo é legível com SR (alt text, labels, aria-live)
+focus            — focus ring visível, ordem lógica, não removido, gerenciado em modais
+semantic HTML    — elementos > divs genéricas (button, heading, nav, main, form)
+contrast         — texto ≥ 4.5:1 (body) / 3:1 (large) / 3:1 (UI components)
+touch targets    — ≥ 44x44px (48x48 recomendado)
+reduced motion   — animações respeitam prefers-reduced-motion
+forms            — labels, errors, hints, e focus sequence
+errors           — comunicados por texto + aria-live, não só cor
+```
+
+## Investigation Procedure
+
+1. **Testar keyboard** — Tab por toda a tela. Todos os elementos interativos são
+   alcançáveis? A ordem de tab é lógica? Há `tabindex` quebrado? (positivo que
+   não é 0, negativo que esconde)
+2. **Testar focus** — O focus ring é visível? Foi removido com `outline: none`? Ao
+   abrir modal, focus vai para dentro? Ao fechar, volta ao trigger? O focus não fica
+   preso em um elemento (focus trap quebrado)?
+3. **Testar screen reader** — Há `alt` text em imagens? Há `aria-label` em ícones
+   semânticos? `aria-live` para conteúdo dinâmico? O conteúdo é legível sem contexto
+   visual? (testar com um leitor real ou simulando: fechar os olhos e ouvir)
+4. **Testar semantic HTML** — `<button>` vs `<div onclick>`? `<nav>` vs `<div>`?
+   `<h1-h6>` para hierarquia? `<form>` com `<label>`?
+5. **Testar contrast** — texto body ≥ 4.5:1 (WCAG AA). Texto large ≥ 3:1. UI
+   components (bordas, ícones) ≥ 3:1. Modo escuro?
+6. **Testar touch targets** — botões, links, inputs ≥ 44x44px. Elementos próximos têm
+   espaço entre eles? (touch não preciona o adjacente)
+7. **Testar reduced motion** — animações desligam com `prefers-reduced-motion: reduce`?
+   (ver `animation-review` para detalhe)
+8. **Testar forms** — cada input tem `<label>` (não só placeholder)? Erros são
+   comunicados por texto (não só cor)? Hints/tooltips são acessíveis (não só hover)?
+   Focus sequence entre campos é lógica?
+9. **Sintetizar** — referenciar `references/frontend.yaml` (Impeccable, WCAG docs)
+   quando apropriado.
+
+## Questions to Ask
+
+* Toda ação é alcançável com Tab/Enter/Esc? (sem mouse trap)
+* O focus ring é visível? Foi removido com `outline: none`? (se sim, todo o resto
+  falha para teclado)
+* Ao abrir modal, focus vai para dentro? Ao fechar, volta? (focus trap correto?)
+* Imagens têm `alt` text descritivo? (não só "image", vazio, ou o filename)
+* Ícones semânticos têm `aria-label`? (não só decorative)
+* Conteúdo dinâmico (loading, erro, toast) tem `aria-live` / `role="alert"`?
+* A estrutura de headings é hierárquica? (h1 → h2 → h3, não pula)
+* `<button>` é usado para ações, não `<div onclick>`?
+* Contraste de texto ≥ 4.5:1? (WCAG AA)
+* Touch targets ≥ 44x44px? (especialmente mobile)
+* Cada input tem `<label>` visível? (não só placeholder)
+* Erros são comunicados por texto + aria-live, não só por cor?
+
+## Attack Patterns
+
+```text
+keyboard trap
+    modal aberto, Tab não sai do modal (correto). Mas não volta ao fechar (erro).
+    dropdown com itens não acessíveis por teclado (só mouse)
+
+focus removed
+    `*:focus { outline: none !important }` — o maior crime de acessibilidade
+    → usuário de teclado não vê onde está
+
+no alt text
+    <img src="chart.png"> sem alt → screen reader lê "chart.png"
+    ícone de like sem aria-label → "button" sem contexto
+
+heading hierarchy broken
+    h1 → h3 (pula h2) → conteúdo perde estrutura
+    tudo é h1 (sem hierarquia)
+
+div as button
+    <div onclick="submit()"> vs <button type="submit">
+    → não acessível por teclado, não tem role, não tem estado
+
+contrast insufficient
+    gray-400 (#9CA3AF) em white (#FFFFFF) → 2.9:1, falha WCAG AA
+
+touch target too small
+    link de 20×20px no mobile → impossível acertar com o dedo
+
+label absent
+    placeholder="Username" como único label → perde contexto quando preenchido
+    → <label> necessário
+
+error by color only
+    input com borda vermelha sem texto de erro → daltônico não vê
+    → precisa de texto + aria-live
+
+reduced motion ignored
+    parallax e flutuação constantes sem `prefers-reduced-motion`
+    → desconforto vestibular
+
+skip navigation absent
+    <main> sem "Skip to content" → usuário de teclado tab pelos 20 links do nav
+    toda vez que carrega
+```
+
+## Evidence Requirements
+
+* **Nomear o eixo** (keyboard/focus/screen reader/semantic/contrast/touch/reduced
+  motion/forms/errors).
+* **Mostrar o elemento exato** e a violação (ex: `*:focus { outline: none !important }`,
+  `alt=""` em imagem informativa, `<div onclick>` para ação, contraste 2.9:1).
+* **Referenciar o critério WCAG** quando aplicável (ex: "WCAG 1.4.3 Contrast Minimum",
+  "2.1.1 Keyboard", "2.4.7 Focus Visible").
+* **Escalar confiança (Accessibility):**
+  * `CONFIRMED` — violação mensurável (contraste < 4.5:1, focus removido, keyboard
+    trap, no alt text, label ausente, touch target < 44px).
+  * `HIGH CONFIDENCE` — padrão claramente violado.
+  * `POSSIBLE` — violação marginal (ex: contraste 4.3:1, touch target 40px).
+  * `SPECULATIVE` — necessidade não confirmada (ex: "talvez precise de aria-live aqui").
+
+## False Positives
+
+* **Decorative image** — `alt=""` é *correto* para imagens decorativas. Não reportar
+  como "alt ausente". (Reportar quando é informativa sem alt.)
+* **Focus visible por outro sinal** — se o `outline: none` tem substituto (border,
+  background, box-shadow) em todos os estados, é aceitável. Confirmar antes de
+  reportar.
+* **Touch target tem espaço extra** — se o target visual é 30px mas o padding faz
+  o hit area ≥ 44px, é ok. Avaliar pelo hit area real, não só pelo visual.
+* **Label oculto mas acessível** — `aria-label`/`<label class="sr-only">` é válido
+  se o screen reader lê. Não exigir label visível se o SR tem contexto suficiente.
+* **Skip navigation em app SPA** — em apps de página única, skip to content pode ser
+  substituído por rota/foco gerenciado. Avaliar o contexto.
+* **Reduced motion com fallback** — se o app respeita reduced motion, as animações
+  que ainda rodam precisam ser avaliadas individualmente, não como "não respeita".
+
+## Output Format
+
+Para cada violação, um finding via `templates/audit-report.md`. Em **Affected
+component**, nomeie o elemento. Em **Reproduction**, descreva o comportamento (ex:
+"Tab 3×: focus vai do header para o footer, pulando todo o conteúdo principal"). Em
+**Root cause**, aponte o eixo e o critério WCAG. Em **Recommendation**, dê a correção
+(adicionar focus ring, `alt` text, `<label>`, contraste, touch target, ARIA, skip
+navigation, reduzir motion).
+
+Apresente por eixo, ordem de severidade: keyboard traps e focus removido (= bloqueante
+para usuário de teclado) primeiro; contrast e labels depois; semantic HTML e touch
+targets em seguida; forms e reduced motion por último.