clarify

Visão geral da skill clarify

A clarify skill ajuda a reescrever textos confusos de UI para que as pessoas entendam o que aconteceu, o que fazer em seguida e por que isso importa. Ela foi feita para trabalho de design UI/UX, especialmente quando um produto tem rótulos vagos, mensagens de erro fracas, instruções difíceis de acompanhar ou microcopy que parece tecnicamente correta, mas ainda confunde usuários reais.

Para que a clarify funciona melhor

Use clarify quando o problema principal não está no layout ou no fluxo de interação, mas no texto dentro da interface:

• labels de botão que não deixam claro o resultado
• mensagens de erro que explicam o sistema em vez de ajudar a pessoa usuária
• empty states sem próximo passo
• textos de ajuda em formulários que pressupõem conhecimento demais
• instruções corretas, mas pesadas demais de processar em momentos de estresse

Isso faz da clarify skill uma ótima opção para product designers, UX writers, times de frontend e founders lapidando texto voltado ao usuário antes do lançamento.

O trabalho real que a clarify faz

Na prática, o papel da clarify é transformar textos de interface confusos ou mal acabados em algo que seja:

• mais fácil de escanear
• mais fácil de colocar em ação
• mais alinhado ao conhecimento da pessoa usuária
• mais adequado ao momento emocional

Esse último ponto é importante. A skill de origem pede explicitamente o nível técnico da pessoa usuária e seu estado mental naquele contexto, o que é muito mais útil do que um pedido genérico de “deixe isso mais claro”.

O que diferencia a clarify de um prompt genérico de reescrita

Um prompt comum pode até gerar um texto mais limpo. A clarify é mais opinativa sobre por que o texto falha:

• jargão
• ambiguidade
• voz passiva
• falta de contexto
• pressupostos ocultos
• tom desalinhado
• detalhe demais ou de menos

Ela também depende de um contexto de design mais amplo. A skill exige /frontend-design e, se esse contexto ainda não existir, /teach-impeccable antes. Essa dependência é importante na decisão de instalação: a clarify não é uma macro isolada para “dar um trato no texto”; ela foi pensada para funcionar dentro de um fluxo maior de UX/sistema de design.

Como usar a skill clarify

Instale a clarify no contexto certo de repositório

O caminho de clarify install segue o sistema de skills do repositório pbakaus/impeccable. Se você usa um ambiente compatível com Skills, adicione o repo e invoque a skill clarify a partir dele. A própria skill fica em:

/.agents/skills/clarify/SKILL.md

Como a evidência do repositório só expõe o SKILL.md, leia esse arquivo primeiro antes de presumir que existam outros assets auxiliares.

Leia este arquivo antes da primeira execução

Comece por:

• SKILL.md

É ali que está a lógica real de operação: preparação obrigatória, critérios de avaliação e o fluxo passo a passo de revisão de copy. Não há scripts de suporte nem referências adicionais expostas aqui, então o principal valor está em seguir a sequência da skill corretamente.

Não pule a dependência obrigatória

Antes de usar a clarify, a skill orienta invocar:

• /frontend-design

E, se ainda não existir contexto de design:

• /teach-impeccable

Esse é o maior ponto de atrito para novos usuários. Se você pular essa preparação, provavelmente vai conseguir um texto razoável, mas com decisões de UX mais fracas. A skill parte do princípio de que os princípios de design e a coleta de contexto já foram feitos.

De que entrada a clarify precisa para funcionar bem

A entrada mínima utilizável para clarify usage é o texto atual e onde ele aparece. Os resultados melhoram quando você também informa:

• tela ou fluxo de destino
• tipo exato de elemento de UI
• nível técnico do público
• estado mental da pessoa naquele momento
• ação desejada após a leitura
• restrições como tom, voz de marca ou limite de caracteres

Sem isso, a skill ainda consegue reescrever o texto, mas não consegue escolher com segurança o nível certo de objetividade, detalhe ou tom emocional.

Melhor formato de prompt para clarify for UI/UX Design

Um pedido fraco:

• “Improve this error message: Authentication failed.”

Um pedido mais forte:

• “Use clarify for UI/UX Design. Rewrite this login error message for non-technical users on mobile. They are likely frustrated and trying to get back into their account quickly. Current text: ‘Authentication failed.’ We want them to understand the problem and next step without sounding robotic. Keep it under 90 characters if possible.”

Essa segunda forma entrega os dados de decisão que faltavam para a skill: público, emoção, contexto de dispositivo e critérios de sucesso.

Transforme um objetivo vago em um prompt utilizável para a clarify

Se o seu ponto de partida for “deixar o texto do app mais claro”, converta isso para a estrutura abaixo:

1. copy atual
2. localização no produto
3. quem é a pessoa usuária
4. o que ela está tentando fazer
5. em que estado emocional ela está
6. que ação ela deve tomar em seguida
7. restrições de tamanho ou tom

Essa estrutura se alinha de perto ao clarify guide implícito no checklist da skill.

Fluxo sugerido para um uso prático da clarify

Um fluxo confiável se parece com isto:

1. Reúna contexto de produto e design com /frontend-design.
2. Confirme o nível do público e o estado mental.
3. Cole a copy original exatamente como aparece.
4. Explique a tela e a ação pretendida da pessoa usuária.
5. Peça primeiro um diagnóstico, depois opções de reescrita.
6. Escolha uma direção e itere em tom, concisão ou especificidade.

Essa etapa de “diagnóstico primeiro” importa porque a skill foi feita para identificar por que o texto não está claro, e não apenas substituí-lo.

Peça para a clarify diagnosticar antes de reescrever

Para extrair mais valor do que um polimento genérico de LLM, peça a saída em duas etapas:

• problemas de clareza encontrados
• alternativas melhoradas

Exemplo:

• “Use clarify. First identify jargon, ambiguity, missing context, assumptions, and tone issues in this onboarding copy. Then provide 3 rewrite options for first-time users.”

Isso ajuda os times a revisar decisões, em vez de só escolher a versão que “soa melhor”.

Onde a clarify é mais forte

A clarify skill rende melhor em textos curtos e de alto impacto na UI, como:

• erros
• labels
• textos de ajuda
• confirmações
• avisos
• empty states
• instruções de configuração

São pontos em que um texto pouco claro gera atrito rapidamente e em que reescritas sensíveis ao contexto podem melhorar de forma concreta as taxas de conclusão e a confiança do usuário.

Onde a clarify é menos indicada

Tenha cuidado se o problema real for:

• fluxo de produto errado
• funcionalidade ausente
• arquitetura da informação ruim
• texto jurídico ou de compliance com pouca margem de mudança
• copy longa de marketing

Nesses casos, a clarify pode melhorar a legibilidade, mas não vai corrigir a causa raiz.

FAQ da skill clarify

A clarify é só para UX writers?

Não. A clarify é útil para designers, PMs, engenheiros e founders que são responsáveis por textos de interface, mas não têm formação em UX writing. O principal requisito é conseguir fornecer contexto suficiente sobre a pessoa usuária e o momento.

A clarify é amigável para iniciantes?

Em grande parte, sim — mas só se você perceber a cadeia de dependências. A skill de origem exige /frontend-design e, possivelmente, /teach-impeccable antes da reescrita. Iniciantes que ignoram essa etapa podem achar que a skill é superficial, quando na verdade o fluxo pretendido começa pelo contexto.

O que a clarify faz melhor do que um prompt comum de “reescreva isso”?

A principal vantagem é o diagnóstico estruturado. A clarify procura causas específicas de confusão, como jargão, ambiguidade, voz passiva, falta de contexto e pressupostos sobre o conhecimento do usuário. Isso normalmente leva a reescritas mais acionáveis para textos de interface.

Quando eu não devo usar a clarify?

Não recorra à clarify quando o texto é apenas um sintoma de um problema mais profundo no produto. Se os usuários estão confusos porque o fluxo está quebrado, as permissões não estão claras ou a UI esconde informações importantes, um texto melhor sozinho não vai resolver.

A clarify é boa para mensagens de erro?

Sim. Esse é um dos casos de uso mais evidentes. A skill leva explicitamente em conta o estado mental da pessoa usuária, o que é crítico em momentos de estresse, como falhas de login, problemas de pagamento ou erros de validação em formulários.

A clarify pode ajudar com tom e voz de marca?

Sim, mas só se você informar as restrições. Se você quer algo como “simples, mas premium”, “amigável, mas sem ser brincalhão” ou “acolhedor em momentos de estresse”, diga isso de forma direta. Caso contrário, a skill vai otimizar principalmente para clareza.

Como melhorar a skill clarify

Dê à clarify o estado da pessoa usuária, não só a frase

A melhoria de maior impacto é descrever a situação da pessoa usuária:

• iniciante ou experiente
• calma ou estressada
• explorando ou tentando se recuperar de uma falha
• desktop ou mobile
• alta atenção ou baixa atenção

Isso afeta diretamente se o melhor texto deve ser mais curto, mais acolhedor, mais explícito ou mais instrucional.

Forneça a UI ao redor, não o texto isolado

Um label ou uma mensagem muitas vezes parece ruim porque falta o contexto ao redor. Para melhorar os resultados da clarify, inclua:

• campos ou botões próximos
• título da página
• etapa anterior
• próxima ação esperada

Uma linha “ruim” pode ser aceitável em uma tela e prejudicial em outra.

Peça múltiplas estratégias de reescrita

Em vez de solicitar uma única resposta, peça opções como:

• versão mais curta e clara
• versão mais acolhedora
• versão mais orientada à ação

Isso é especialmente útil em clarify for UI/UX Design, porque os times frequentemente precisam equilibrar concisão, tom e orientação.

Use cedo as restrições de caracteres ou layout

Se o texto precisa caber em um botão, toast, modal ou campo de formulário mobile, diga isso logo no início. Caso contrário, a clarify pode gerar um texto mais claro em teoria, mas inviável na interface real.

Fique atento aos modos de falha mais comuns

Mesmo com a clarify, times costumam aprovar reescritas que são:

• mais claras, mas longas demais
• mais amigáveis, mas vagas
• precisas, mas técnicas demais
• polidas, mas desconectadas da tarefa real

Revise a saída com base na ação que você quer provocar no usuário, não apenas na qualidade da redação.

Itere no diagnóstico, não só no texto

Se o primeiro resultado não acertar o alvo, não peça apenas uma versão mais curta. Pergunte o que a skill pode ter entendido errado:

• suposição incorreta sobre o público
• estado mental errado
• falta de contexto do produto
• simplificação excessiva
• pouca explicação sobre os próximos passos

Isso melhora as próximas saídas mais rápido do que uma edição superficial.

Combine a clarify com uma revisão em nível de tela

Na prática, a melhor forma de melhorar a clarify skill é usá-la como parte de uma revisão de tela, não como uma ferramenta para consertar frases isoladas. Revise toda a copy relacionada em conjunto:

• título da página
• labels de campo
• textos de ajuda
• textos de validação
• label de CTA
• mensagem de sucesso ou erro

Assim você captura inconsistências que uma reescrita de linha única deixaria passar.

Mantenha um template reutilizável de prompt para clarify usage

Um template simples e reutilizável:

• “Use clarify. Context: [screen/flow]. Audience: [user type]. Mental state: [emotion/urgency]. Current copy: [text]. Goal: [desired action]. Constraints: [tone/length/brand]. First diagnose the clarity issues, then give 3 rewrite options.”

Isso torna o clarify usage mais consistente entre equipes e reduz pedidos com pouco contexto que acabam gerando saídas genéricas.