audit

Visão geral da skill audit

O que a skill audit faz

A skill audit executa uma UX Audit técnica sobre frontend já implementado e transforma os achados em um relatório estruturado. Ela verifica qualidade mensurável em acessibilidade, performance, theming, comportamento responsivo e anti-patterns de implementação, depois pontua cada área e classifica os problemas por severidade de P0 a P3.

Para quem vale instalar a audit

A skill audit é mais indicada para frontend engineers, design engineers, UX engineers e agentes de IA que precisam revisar uma página, componente ou funcionalidade antes do release. Ela é especialmente útil quando você quer uma auditoria repetível, em vez de um prompt vago como “revise essa UI”.

O trabalho real que ela resolve

A maioria dos usuários não precisa de feedback genérico. Precisa de uma auditoria que:

• foque em problemas sustentados pelo código
• separe defeitos críticos de ajustes de acabamento
• evite sair corrigindo tudo cedo demais
• deixe um relatório pronto para handoff e implementação posterior

Esse é o valor central aqui: uma revisão técnica de qualidade que você pode rodar antes de pedir para outra skill ou agente fazer mudanças.

O que diferencia essa audit de um prompt genérico

O principal diferencial está na disciplina de escopo. A skill trata explicitamente a audit como revisão técnica, não como crítica de gosto visual. Ela pede uma varredura diagnóstica em cinco dimensões, usa um modelo de pontuação consistente e espera um relatório por severidade com plano de ação. Isso facilita comparar resultados entre páginas e transformar a saída em tarefas de follow-up.

Principal ressalva antes de adotar

Esta skill depende de contexto prévio. As próprias instruções exigem chamar $frontend-design primeiro e, se ainda faltar contexto de design, executar $teach-impeccable antes da audit. Se você pular essa preparação, a qualidade da saída cai, porque a auditoria depende de princípios de design compartilhados e de regras de coleta de contexto.

Como usar a skill audit

Instalação da audit e contexto de setup

Instale a skill audit a partir do repositório pbakaus/impeccable no seu ambiente de skills:

npx skills add pbakaus/impeccable --skill audit

Como esta skill fica em .codex/skills/audit, a decisão prática de instalar tem menos a ver com dependências e mais com encaixe no seu fluxo de trabalho. O esperado é usá-la em um ambiente que suporte invocação de skills e outras skills relacionadas do mesmo repositório.

Leia este arquivo primeiro

Comece por:

• SKILL.md

Esse arquivo concentra praticamente todo o comportamento relevante: pré-requisitos, escopo da audit, pontuação e estilo de relatório esperado. Não há scripts auxiliares nem arquivos de referência visíveis nessa pasta da skill, então a maior parte da orientação de uso está no próprio documento principal da skill.

Pré-requisito obrigatório antes de rodar a audit

Não chame audit do nada. A skill manda invocar $frontend-design primeiro, porque é ali que estão os princípios de design, os anti-patterns e o protocolo de coleta de contexto usados por esta auditoria. Se ainda não existir contexto de design, rode $teach-impeccable antes da audit.

Na prática, a sequência é:

1. reunir contexto de design e produto
2. definir qual página ou componente será revisado
3. rodar audit
4. usar o relatório para orientar correções com outra tarefa ou skill

Que entradas a skill audit precisa

A skill audit funciona melhor quando você fornece um alvo concreto junto com contexto de revisão. Boas entradas normalmente incluem:

• a página, rota, componente ou fluxo exato
• a localização do código ou os arquivos envolvidos
• os dispositivos-alvo pretendidos
• detalhes de framework ou stack, se forem relevantes
• restrições conhecidas, como CSS legado, limites do design system ou budgets de performance
• se a revisão é pré-release, focada em regressão ou exploratória

Um pedido fraco seria “audite meu app”. Um pedido forte seria “rode uma audit na página de checkout em mobile e desktop, com foco em acessibilidade, comportamento de carregamento e breakpoints responsivos”.

Transforme um objetivo solto em um prompt de audit utilizável

Um bom prompt de uso da audit deve nomear o alvo, definir o perímetro e pedir saída estruturada. Por exemplo:

• “Run the audit skill on the pricing page. Review accessibility, performance, theming consistency, responsive behavior, and implementation anti-patterns. Score each dimension 0-4, list P0-P3 issues, and end with an action plan. Do not fix anything yet.”
• “Use audit for the settings modal component. Check keyboard support, semantic structure, focus handling, contrast, theme token usage, and mobile layout failure points.”

Isso funciona melhor do que um prompt genérico de review porque segue o modelo de relatório da própria skill.

O que a audit realmente verifica

Pelas instruções da skill, a audit cobre cinco dimensões:

• acessibilidade
• performance
• theming
• design responsivo
• anti-patterns

A seção de acessibilidade é a mais explícita na fonte e inclui contraste, ARIA, navegação por teclado, HTML semântico, alt text e problemas de formulário. Isso mostra que a skill pensa a partir da implementação e tende a encontrar defeitos concretos, não conselhos abstratos.

Formato de saída esperado e por que isso importa

O valor desta skill audit não está só no checklist. Está no formato da saída:

• revisão por dimensão
• pontuação 0-4 por dimensão
• severidade P0-P3
• plano acionável

Essa estrutura ajuda na triagem. O time consegue separar bloqueadores de release de melhorias de backlog sem precisar reler o relatório inteiro.

Melhor fluxo de trabalho para usar a audit

Um fluxo prático se parece com isto:

1. preparar o contexto de design com as skills pré-requisito
2. escolher uma página, funcionalidade ou componente
3. fornecer escopo de implementação e restrições
4. rodar a skill audit
5. revisar pontuações e severidades
6. transformar o plano de ação em tickets ou em um prompt posterior de correção

Esta skill funciona melhor quando aplicada em superfícies delimitadas. Se você tentar auditar um produto inteiro de uma vez, os achados tendem a ficar rasos e a priorização piora.

Quando usar audit para UX Audit

Use audit for UX Audit quando você precisar de evidência de implementação para problemas de qualidade de UX. É uma opção forte para:

• revisões de prontidão para release
• checagens de regressão após um redesign
• comparação de qualidade técnica entre páginas
• identificação de defeitos de acessibilidade e responsividade antes de testes com usuários
• geração de uma lista de defeitos para outro agente corrigir

Ela é menos adequada para perguntas puramente de pesquisa, como arquitetura da informação, clareza de mensagem ou exploração visual de marca.

Limites e casos em que não encaixa bem

Esta não é uma skill de crítica de design nem uma skill de correção. Ela documenta problemas em vez de resolvê-los. Se o seu objetivo real é “deixar essa página mais bonita”, só faz sentido instalar se você também quiser um inventário técnico de defeitos. Se o objetivo é “reescrever o componente agora”, essa etapa de audit pode ser desnecessária, a menos que o risco de qualidade seja alto.

FAQ da skill audit

Esta skill audit é amigável para iniciantes?

Sim, desde que você já saiba qual superfície quer revisar. A skill oferece um enquadramento claro de auditoria, mas iniciantes podem deixar passar a etapa de contexto pré-requisito. Se você ignorar $frontend-design e $teach-impeccable quando necessário, a audit pode ficar genérica ou inconsistente.

Eu preciso do repositório impeccable inteiro?

Para esta skill, a principal dependência é conceitual, não baseada em muitos arquivos. A pasta visível da audit expõe apenas SKILL.md, mas as instruções dependem explicitamente de outras skills do mesmo repositório. Então, na prática, você provavelmente vai querer acesso ao repositório como um todo, e não apenas a este arquivo isolado.

Como a audit é melhor do que pedir para uma IA revisar minha UI?

Um prompt comum costuma misturar gosto subjetivo de design com defeitos técnicos. Esta skill audit impõe um escopo mais estreito, dimensões consistentes e saída pontuada. Isso normalmente gera triagem melhor, comparabilidade melhor entre auditorias e menos tempo perdido discutindo comentários vagos.

A audit consegue corrigir problemas automaticamente?

Não. A skill foi feita para diagnosticar e reportar. Isso é uma vantagem, não uma limitação, se você quer uma separação limpa entre revisão e implementação. Use o relatório para alimentar uma tarefa de correção separada.

O que eu deveria auditar primeiro?

Comece por uma superfície de alto impacto:

• hero e navegação da homepage
• fluxo de cadastro ou checkout
• tela de entrada do dashboard
• componentes compartilhados como modais, formulários e tabelas

Essas áreas expõem rapidamente problemas de acessibilidade, responsividade e performance, o que torna a primeira audit mais útil.

Quando eu não deveria usar esta skill audit?

Pule esta audit se:

• você só quer ideias subjetivas de design
• não há implementação concreta para inspecionar
• você precisa de pesquisa completa de produto, e não de revisão técnica
• pretende lançar um protótipo rápido e não precisa de relatório com pontuação

Como melhorar a skill audit

Dê um alvo mais fechado para a audit

A forma mais rápida de melhorar a saída da audit é reduzir o escopo. Peça uma rota, um fluxo ou uma família de componentes. “Audite o fluxo de exclusão de conta” vai gerar achados mais fortes do que “audite o app inteiro”.

Forneça o contexto que a skill espera

Como esta audit depende de contexto de frontend design, entregue o pano de fundo que estiver faltando logo no início:

• objetivo do usuário naquela tela
• modelo de interação esperado
• prioridades de dispositivo
• regras de tema ou design system
• restrições de negócio

Isso reduz falsos positivos e ajuda a audit a avaliar anti-patterns à luz da intenção real.

Peça apenas achados sustentados por evidência

Se você quiser uma audit mais forte na prática, peça explicitamente evidência observável. Por exemplo, solicite que o agente cite o elemento, padrão, estado ou comportamento por trás de cada achado. Isso mantém o relatório mais próximo da realidade da implementação e mais fácil de validar.

Melhore a qualidade da severidade com contexto de release

Os rótulos de severidade ficam melhores quando você define impacto. Diga à audit se o alvo é:

• página pública de marketing
• UI autenticada do produto
• fluxo de checkout ou conversão
• ferramenta interna
• experiência mobile-first

Um keyboard trap no checkout deve receber uma classificação diferente de uma inconsistência cosmética de espaçamento em uma tela administrativa.

Modos de falha mais comuns ao usar a audit

Os problemas mais comuns são:

• pular as skills pré-requisito obrigatórias
• auditar área demais de uma vez
• pedir correções em vez de diagnóstico
• não fornecer contexto de dispositivo ou viewport
• tratar preferências subjetivas de design como defeitos técnicos

Esses erros normalmente levam a relatórios mais ruidosos, priorização mais fraca ou escopo misturado.

Entradas mais fortes que melhoram a qualidade da saída

Prompts melhores incluem especificações como:

• “focus on keyboard navigation and forms”
• “treat mobile Safari as a priority”
• “check theme token consistency in dark mode”
• “flag only measurable anti-patterns”
• “score each dimension and end with top 5 fixes by impact”

Esses detalhes melhoram a audit porque indicam onde vale aprofundar mais.

Como iterar depois da primeira audit

Depois da primeira rodada, não rode exatamente o mesmo prompt amplo de novo. Em vez disso:

1. corrija ou priorize os problemas de maior severidade
2. rode a audit novamente na mesma superfície delimitada
3. peça verificações mais profundas na dimensão com pior pontuação
4. compare as mudanças de score e os achados P0-P1 ainda não resolvidos

Isso transforma a skill audit em uma barreira de qualidade repetível, em vez de um relatório pontual.

Combine a audit com trabalho de implementação posterior

A skill audit é mais forte quando usada como etapa de diagnóstico em um fluxo de duas fases. Primeiro, gere o relatório. Depois, use esse relatório como entrada estruturada para uma etapa separada de implementação. Isso preserva a objetividade da audit e evita que “revisar enquanto edita” esconda defeitos importantes.