Communitygithub.com

ai-states

Projete todos os momentos que um recurso de IA ou agente mostra além da resposta correta – primeiro uso, processamento, não saber, estar incerto, recusar, falhar, ser corrigido, transferir para um humano e, para agentes, toda a delegação (plano, permissões, trabalho não supervisionado, “precisa de você”, devolução, revisão, desfazer, memória) – como um quadro de estados com texto exato, especificação implementável, testes e métricas. Use sempre que o usuário projetar, especificar, revisar ou auditar um recurso baseado em LLM ou IA – chatbot, copiloto, assistente, busca com IA, resumidor, botão “gerar com IA” ou um agente que age, usa ferramentas ou trabalha em segundo plano – ou perguntar o que a IA deve mostrar ou dizer enquanto carrega, quando não sabe, está errada, recusa ou erra; como mostrar fontes ou confiança; quanta autonomia dar a um agente, quando ele deve pedir aprovação, como mostrar o que fez; ou disser “estados de la IA”, “qué pasa cuando la IA no sabe”, “UX de agentes”, “AI UX”, “human in the loop”, “conversation design”, mesmo que eles...

O que é ai-states?

O `ai-states` é uma skill especializada em projetar e especificar todos os momentos de interação de um recurso de IA, além da “resposta boa” – ou seja, cobrindo estados como primeiro uso, carregamento, não saber, recusar, falhar, ser corrigido e transferir para um humano. Ela também abrange toda a dinâmica de delegação para agentes que agem de forma autônoma: planejamento, permissões, trabalho não supervisionado, devolução de controle e desfazer. A skill fornece um processo completo em 10 etapas, começando com a compreensão do recurso e dos sinais disponíveis no sistema, passando pela avaliação do nível de risco (baixo, médio, alto), análise de modos de falha, mapeamento de estados, especificação detalhada com formato padronizado (gatilho, o que mostra, texto, ações, o que preserva, para onde vai, teste e métrica), criação de um quadro visual (`board.html` a partir de template), redação de texto, escrita de scripts de teste e métricas, e revisão final. É compatível com qualquer plataforma de IA ou agente (Claude Code, Cursor, Codex, etc.) e pode ser usada de forma interativa ou não interativa, assumindo respostas mais prováveis quando necessário e marcando dependências para confirmação. O resultado é um quadro de estados, especificação e lista de suposições – ferramentas essenciais para desenvolvedores e designers garantirem que o usuário sempre saiba o que a IA está fazendo, em que se baseia e o que pode fazer a seguir, construindo confiança calibrada.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/milagrosgonzalezarguello-des/ai-states-skill/tree/HEAD/ai-states

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Estados da IA

Projete os momentos em que um recurso de IA mostra algo além daquele em que funciona.

As equipes projetam a demonstração: o usuário pergunta, a IA responde, todos aplaudem. Depois, pessoas reais usam. Elas perguntam algo que a IA não pode fazer, leva quatorze segundos, responde com total confiança e erra, a conexão cai no meio da frase, e o produto mostra um spinner e "Algo deu errado". Agora que a IA também age – envia, agenda, edita e continua trabalhando enquanto ninguém observa – os momentos não projetados são piores: ela fez algo, e o usuário não consegue dizer o quê.

Portanto, o trabalho não é "projetar o chat". É: a cada momento, o usuário sabe o que a IA está fazendo, em que se baseia e o que pode fazer em seguida – e, quando ela age por ele, o que fez e como desfazer.

O objetivo é a confiança calibrada: os usuários confiam no recurso tanto quanto ele merece, caso a caso. Ambas as formas de erro são falhas – aceitar sem verificar e refazer tudo manualmente.

O que todo recurso de IA deve acertar

Verifique estes primeiro. Eles são o que um usuário nota quando estão ausentes.

  1. Nunca um spinner vazio. Após cerca de dois segundos, o usuário precisa saber o que está acontecendo e, após dez, como pará-lo ou sair.
  2. Quatro "nãos" diferentes. Não sabe (sem informação), não pode (não é algo que faz), não vai (não é permitido) e quebrou (falha do sistema) têm causas diferentes e próximos passos diferentes. Um erro genérico para todos os quatro faz com que os usuários tentem novamente coisas que nunca funcionarão.
  3. Não saber é um estado projetado, não um erro. "Não encontrei isso em seus documentos" é uma boa resposta. É o que torna as outras respostas confiáveis.
  4. Nada parece completo quando não está. Um resultado parcial que parece completo é o estado mais perigoso que existe, porque ninguém o verifica.
  5. Os limites são ditados de antemão. O usuário aprende o que ele pode e não pode fazer desde a primeira tela, não ao falhar.
  6. Todo beco sem saída tem uma saída, e nada que o usuário deu é perdido: o que digitou, anexou ou selecionou, e o resultado anterior, ainda estão lá após qualquer falha.
  7. Verificar custa menos que refazer. As respostas mostram em que se baseiam, na proporção das consequências – a fonte ao lado da afirmação, as páginas cobertas, a data em que está atualizada. Se verificar significa fazer o trabalho novamente, o recurso não economiza nada.
  8. Antes de agir, mostra; depois de agir, pode ser desfeito. Qualquer coisa que envie, exclua, pague ou altere algo ganha uma prévia e uma confirmação quando não puder ser revertida. Confirme o que importa, não tudo: prompts constantes treinam as pessoas a aprovar sem ler.
  9. O trabalho feito sem supervisão retorna como um relatório, não como um elogio: o que foi feito, o que não foi, o que não foi verificado e onde olhar primeiro.
  10. Diz apenas o que o sistema pode saber. Nenhum rótulo de confiança que o modelo não pode respaldar, nenhum "verifiquei" quando nada foi verificado, nenhum "lembrarei" quando nada está armazenado.

Como trabalhar

  1. Entenda o recurso antes de desenhar qualquer coisa. Você precisa: o que a IA faz e para quem; a superfície (leia references/surfaces.md, incluindo se o chat é a superfície certa); o que ela lê e o que pode alterar; o que o sistema pode realmente detectar e expor – streaming, fontes, um sinal de recusa, uma pontuação de recuperação, tipos de erro, eventos de etapa; se existe um fallback humano; idioma e registro. Leia o que o usuário lhe deu e, em seguida, pergunte o que está faltando em uma rodada. Se você não puder perguntar (uma execução não interativa ou o usuário estiver ausente), assuma a resposta mais provável, marque cada gatilho que depende dela para confirmar e liste as suposições. Não invente capacidades: um estado que o sistema não pode detectar não pode ser construído. Isso é diferente de um sinal que a equipe precisa construir: se um estado de que o recurso precisa depende de algo que o sistema ainda não expõe (um tipo de erro, uma flag de recusa), projete o estado e liste o sinal como a construir na tabela de sinais – essa tabela é frequentemente a coisa mais útil que a engenharia recebe de você.

  2. Defina as consequências. Elas decidem o quanto cada estado precisa.

    ConsequênciasExemplosO que muda
    Baixasbrainstorming, reescrever uma frase, perguntas casuaisToque leve: regenerar e editar são a rede de segurança
    Médiasresumos nos quais as pessoas agem, respostas sobre a própria conta ou dados da empresa do usuárioFontes, escopo visível, um claro "não encontrado"
    Altasdinheiro, saúde, jurídico, segurança, qualquer coisa enviada a outros ou irreversívelConfirmação antes de agir, evidência no caminho, uma rota humana, uma trilha de auditoria

    As consequências vêm do que as pessoas fazem com a saída, não de se a IA age: um resumo somente leitura de um contrato no qual os advogados confiam é de alto risco. Para um recurso de alto risco que não realiza ações, "alto" significa evidência no caminho, cobertura visível e uma rota humana – não há nada a confirmar.

  3. Percorra as formas de falha (references/failure-modes.md). A maioria é silenciosa: uma resposta fluente e errada, uma omissão, um agente fazendo mais do que foi solicitado, uma instrução plantada em um documento. Para cada uma que pode acontecer aqui, nomeie o estado ou padrão que a defende.

  4. Construa o mapa de estados. Percorra cada estado em references/states.md e marque:

    • Aplica-se – sim, não (com o motivo) ou somente se existir um sinal que você não pôde confirmar.
    • Hoje (ao revisar algo que existe) – projetado, incompleto (existe, mas carece de algo que as consequências exigem – diga o quê), genérico (um curinga o trata) ou ausente.

    Um estado somente se recebe um bloco de especificação e uma linha no mapa, conta como "a confirmar" na faixa de cobertura, e ganha um cartão apenas quando for provável o suficiente para valer a pena desenhar.

    Se a IA executar várias etapas, usar ferramentas por conta própria ou trabalhar enquanto o usuário estiver ausente, faça o mesmo com os estados de delegação em references/delegation.md, e preencha o nível de autonomia e a tabela de permissões para cada tipo de ação. Um chat que realiza uma ação após o usuário confirmar não é um agente: o estado 5 (com sua tela "após confirmar" e o desfazer) cobre, mais uma tabela de permissões de três colunas. Não force D1-D12 sobre ele. Não pule o mapa mesmo quando o usuário perguntou sobre um único estado: diga quais outros o recurso precisa.

  5. Especifique cada estado que se aplica no formato abaixo.

  6. Desenhe o quadro. Comece a partir de assets/template.html: um cartão por estado, mostrando o componente real naquele estado com o texto final. Uma lista de estados em prosa é recebida com um aceno de cabeça; um quadro onde as lacunas estão visivelmente ausentes é corrigido. Use a aparência do próprio produto, se ela foi fornecida (cores, componentes, capturas de tela); caso contrário, mantenha o estilo neutro do modelo e diga isso. Desenhe a superfície real do recurso: um recurso de botão e painel ganha painéis, não balões de chat. Um estado que precisa de várias telas (antes e depois de confirmar) permanece um cartão com essas telas. Para um novo design, exclua o bloco de descobertas do modelo e a coluna Hoje do mapa, e deixe a linha de cobertura dizer quantos estados se aplicam, quantos não e quantos aguardam um sinal.

  7. Escreva o texto seguindo references/copy.md, no idioma e registro do produto.

  8. Escreva o roteiro de teste e as métricas (references/measure.md): uma entrada que provoca cada estado e o que registrar para ele.

  9. Revise em relação a references/checklist.md e references/anti-patterns.md, olhando para o quadro renderizado, não para a fonte. python scripts/screenshot.py board.html board.png renderiza uma imagem que você pode abrir (navegadores em aplicativos geralmente recusam arquivos locais); adicione --tile 1400 para obtê-la em fatias legíveis quando o quadro for longo. Se você alterar o quadro depois de olhar, renderize novamente.

  10. Entregue o quadro, a especificação e uma lista curta do que você assumiu e do que precisa de resposta. Diga o que você verificou e o que não verificou.

O que ler. Sempre: states.md, copy.md, checklist.md e a seção de surfaces.md para esta superfície. Para uma revisão, também failure-modes.md e anti-patterns.md. Apenas para agentes (várias etapas, ferramentas, trabalho não supervisionado): delegation.md. measure.md quando você escreve o roteiro de teste.

Os estados

Quatorze estados de resposta em cinco momentos. Cada um é detalhado em references/states.md com o que o usuário precisa, o padrão, o antipadrão e o texto.

MomentoEstadoO usuário está perguntando
Antes1. Primeiro usoO que é isso e o que posso perguntar?
2. CompondoO que será usado? Minha entrada está bem?
Durante3. TrabalhandoEstá fazendo algo? Quanto tempo? Posso parar?
4. Precisa de esclarecimentoO que precisa de mim?
5. Precisa da minha autorizaçãoO que exatamente está prestes a fazer?
Resposta6. RespostaEm que isso se baseia? O que posso fazer com isso?
7. Resposta parcialQual parte está pronta e qual não está?
8. InseguroQuanto devo confiar nisso?
Não9. Não sabeNão há resposta, ou não procurou no lugar certo?
10. Não pode fazer issoQuem ou o que pode?
11. Não vai fazer issoSou eu ou a regra? O que posso perguntar em vez disso?
12. QuebrouPerdi meu trabalho? Tento novamente?
Depois13. CorrigidoAceitou minha correção? Vai acontecer de novo?
14. Transferido para um humanoQuem está com isso agora, o que sabem e quando?

Doze estados de delegação, para IA que age. Detalhados em references/delegation.md.

EstadoO usuário está perguntando
D1. BriefEla entendeu o trabalho e seus limites?
D2. PlanoComo ela vai fazer e posso mudar isso?
D3. PermissãoO que exatamente estou deixando ela tocar e por quanto tempo?
D4. Trabalhando sem supervisãoEla ainda está no caminho certo? Preciso ficar de olho?
D5. Precisa de vocêO que ela está esperando e o que acontece se eu não responder?
D6. RedirecionadoEla aceitou a nova instrução?
D7. DevoluçãoO que ela fez, o que não fez e onde olho primeiro?
D8. Revisão em escalaQuais dessas 140 mudanças realmente preciso examinar?
D9. Desfazer e repararPosso desfazer – tudo ou apenas isso?
D10. Deu errado enquanto ausenteQuão grave é e onde parou?
D11. AprendeO que ela agora assume sobre mim?
D12. Age em relação a outrosO que outras pessoas veem – e sabem que foi a IA?

Para um agente que trabalha em segundo plano sem conversa, vários estados de resposta são substituídos por sua contraparte de delegação, em vez de desenhados duas vezes: Compondo por D1 Brief, Trabalhando por D4, Precisa de esclarecimento por D5. Marque o estado de resposta como "não – veja D4" no mapa. Um trabalho recorrente (toda noite, toda segunda-feira) tem um brief e um plano permanentes: D1 e D2 são as configurações que o usuário revisa uma vez e pode ver antes de cada execução. Em tal quadro, você pode ordenar os cartões por tempo (antes, enquanto funciona, quando devolve) em vez dos cinco momentos, se isso for melhor para a leitura; mantenha os números dos estados.

Uma ação que o próprio produto rejeita por um motivo comercial (saldo insuficiente, data já ocupada) não é nenhum dos quatro "nãos" sobre a IA: mostre-a como uma tela do estado 5, com o motivo do sistema e o que o usuário pode alterar.

Quatro coisas atravessam todos eles e vão para o quadro como notas: interrupção, memória, proatividade (a IA fala primeiro) e custo (créditos, cotas, gastos). Veja o final de references/states.md.

Se você puder projetar apenas cinco: Trabalhando, Não sabe, Quebrou, Resposta parcial e Precisa da minha autorização quando age (Devolução quando trabalha sem supervisão). Esses são onde a confiança é perdida mais rapidamente.

Formato de especificação

Um bloco por estado, nesta ordem. Os desenvolvedores constroem a partir do gatilho; sem ele, o estado é um desejo.

### 9. Não sabe
- **Gatilho:** a recuperação não retorna nenhuma passagem acima do limite. (a confirmar: o valor do limite)
- **Mostra:** o balão de resposta, estilo neutro (não o estilo de erro).
- **Texto:** "No encontré información sobre licencias por mudanza en las políticas de RR. HH."
- **Ações:** Reformular · Ver as políticas · Perguntar ao RH
- **Preserva:** a pergunta, editável.
- **Leva a:** 2 Compondo, ou 14 Transferido para um humano.
- **Teste:** "¿Hay licencia por mudanza?"
- **Métrica:** `answer_not_found` com a consulta; monitore a taxa por tópico.
- **Pergunta em aberto:** o sistema consegue distinguir "sem documentos" de "documentos existem, mas o usuário não tem acesso"?

Traduza os rótulos (Gatilho, Mostra, Texto...) quando a equipe trabalha em outro idioma: Gatilho, Mostra, Texto, Ações, Preserva, Leva a, Teste, Métrica, Pergunta em aberto.

Preserva é tudo o que o usuário perderia: texto digitado, anexos, a seleção, o resultado anterior, o trabalho que um agente já havia feito.

Idioma e registro

Escreva no idioma que o usuário solicitar; se ele não disser, use o idioma da solicitação e do produto. O registro é uma escolha do produto, não um padrão: descubra como o produto já fala (você, tu; formal ou caloroso) e mantenha-o em todos os estados. O estado de erro é onde as equipes escorregam para outra voz – um formal "Ocorreu um erro" dentro de um produto que diz "Pronto!" em todos os outros lugares parece uma empresa diferente.

Dois idiomas podem estar em jogo. O texto – tudo dentro das telas desenhadas – está no idioma e registro do produto. O quadro e a especificação ao redor – nomes de estados, cabeçalhos, os rótulos da especificação, suas notas – estão no idioma em que a equipe trabalha, que é o idioma em que o usuário escreveu para você. Não deixe os cabeçalhos em inglês do modelo em um quadro para uma equipe de língua portuguesa. Os exemplos nos arquivos de referência estão em espanhol formal e inglês; eles mostram o padrão, então reescreva-os no registro do produto em vez de copiá-los.

A própria voz da IA: se o produto fizer a IA falar em primeira pessoa, mantenha o "eu" para o que ela fez ("Não encontrei...", "Usei os três arquivos"), não para sentimentos que ela não tem ("Adoraria ajudar"). Se o recurso não tem persona – um botão, um painel – escreva na voz impessoal do produto ("Não foi possível ler o arquivo").

Habilidades Relacionadas