jordyfontoura/skills

# Escrever a descrição de um PR

Use `tratar-revisao` para feedback recebido e `integrar` para integração autorizada entre
branches ou merge de PR. Escrever a descrição continua sendo uma tarefa distinta dessas ações.

Escreva para quem não acompanhou a conversa. Siga o modelo de PR do repositório, quando houver.
Comece pelo problema concreto e pelo comportamento resultante; inclua um exemplo de antes
e depois quando ele ajudar. Aponte para os requisitos, o plano ou a decisão relevante.

Para mudanças simples, use uma descrição curta e as evidências. Para mudanças maiores,
separe comportamento, validação e risco apenas quando ajudar a leitura. Explique escolhas
importantes, efeitos de compatibilidade e o que uma reversão não restauraria. Identifique
os pontos de uso ou os dados afetados em vez de alegar baixo risco sem justificativa.

# Diagnosticar uma falha

Avalie primeiro o impacto. Se houver dano em curso, priorize uma mitigação dentro da autorização
existente, preservando evidências antes de alterá-las quando possível. Não aguarde a causa
completa para conter um incidente, mas não trate restauração do serviço como causa demonstrada
ou correção definitiva. Sem autorização para mitigar, relate o limite e investigue por meios permitidos.

Encontre um sinal reproduzível do sintoma antes de escolher a correção definitiva: teste, cenário CLI/HTTP,
interação na interface, repetição de uma sequência ou script específico. Confirme que a falha
ocorre pelo motivo esperado. Para instabilidade, registre frequência e condições de ocorrência.
Para desempenho, registre uma medição inicial e o limite esperado antes de alterar o código.

Para regressões, compare com a última revisão conhecida que funcionava e examine mudanças
recentes de código, configuração, dependências e carga. Quando houver histórico e um sinal

# Especificar o trabalho

Leia o pedido, as instruções do projeto, o código relevante, os planos e as decisões existentes.
Use `entrevistar` apenas para escolhas não resolvidas que mudem escopo ou design. Preserve
a etapa da última passagem de contexto e as autorizações existentes.

Antes de elaborar, confira a seleção de modelo e esforço do pedido e de `roles.planner`,
quando houver política local, seguindo `delegar`. Use um contexto compatível com essa seleção;
se o atual não corresponder, delegue ao `planner` quando autorizado. Sem contexto compatível
ou delegação disponível, informe o limite antes de elaborar; não apresente outro modelo como o escolhido.
Sem política ou escolha explícita, preserve a seleção do ambiente. Ler a política não troca
o modelo da conversa nem autoriza delegação.

Declare objetivo, contexto, exclusões, riscos e condição observável de conclusão. Separe

# Examinar a arquitetura existente

Defina a pergunta e o recorte: uma mudança difícil, um módulo, um fluxo ou uma área recorrente
do código. Leia instruções, glossário, decisões e arquitetura documentada. Use as ferramentas
de leitura permitidas; não edite, execute testes que alterem estado ou delegue por invocar esta skill.
`revisar` examina um diff fixo; `reconciliar` compara requisitos e estado. Aqui o objeto é a estrutura
existente e o custo concreto de entendê-la, alterá-la ou testá-la.

## Procurar atrito demonstrável

Siga um fluxo real dos pontos de entrada aos dados, integrações e efeitos. Confira chamadas,
contratos e limites de responsabilidade antes de julgar a organização pelos nomes dos arquivos.
Quando útil e permitido, use histórico de mudanças para localizar áreas recorrentes. Frequência
de edição, tamanho ou quantidade de arquivos são pistas, não defeitos por si sós.

# Implementar o trabalho combinado

Leia o pedido, o plano aplicável, os critérios de aceite, as decisões relevantes e a última
passagem de contexto. Retome a etapa exata. Não reinicie discussões de design resolvidas
nem assuma trabalho sob responsabilidade de outro colaborador.

Inspecione a branch e as alterações locais. Execute as verificações iniciais relevantes
e relate falhas preexistentes. Declare os arquivos ou módulos sob sua responsabilidade quando
o trabalho for compartilhado. Preserve edições alheias e faça mudanças sobrepostas em sequência.

Implemente e comprove uma parte útil por vez. Numa entrega em fases, comece cada fase pela
jornada representativa do plano, com a fixture aprovada, e depois amplie os casos específicos.
Leia [testing.md](testing.md) ao adicionar testes ou ordenar verificações.
Para interfaces, leia [interface.md](interface.md). Use `tratar-revisao` ao tratar feedback

# Integrar trabalho verificado

Leia o pedido e as convenções do projeto. Identifique repositório, branch ou PR de origem,
destino, revisão atual e ação autorizada: atualizar uma branch, integrar localmente, publicar
ou fazer merge remoto. Diferencie trazer a base para a branch de integrar a branch na base.
Use o destino já definido; se uma escolha essencial continuar aberta, esclareça apenas ela.
Um pedido vago para terminar o trabalho não escolhe sozinho publicação, destino ou descarte.

## Preparar a integração

Inspecione estado Git, histórico, relação entre as branches, commits envolvidos, diff e checks
aplicáveis. Confira se as referências locais refletem o estado remoto quando isso afetar a ação.
Não confunda branch com nome parecido, PR aprovado de outra revisão ou testes de um SHA anterior
com a revisão que será integrada. Uma branch não precisa ser integrada se o resultado já está

# Prototipar uma questão

Identifique a pergunta que o experimento precisa responder. Deduza-a do pedido quando estiver
clara; pergunte apenas se a ambiguidade mudar o experimento. Reutilize a linguagem visual
e as interfaces do projeto quando útil. Escolha o meio mais simples que demonstre a dúvida:
página independente, script pequeno ou simulação isolada.
Para direção visual, estados e acessibilidade de interfaces, leia o apoio
`interface.md` da skill `implementar`, respeitando as simulações próprias do protótipo.

Mantenha o protótipo separado do código de produção, em local permitido para experimentos
ou artefatos. Dê uma forma clara de executar ou visualizar. Acrescente apenas os mecanismos
necessários à pergunta; identifique dados inventados e persistência simulada. Não transforme
exploração numa implementação de produção.

# Conferir o estado do trabalho

Comece pela pergunta e pelo escopo: funcionalidade, pendências, versão ou projeto inteiro.
Leia instruções aplicáveis, decisões estabelecidas e última passagem de contexto. Identifique
requisitos, implementação, branches e evidências pelas ferramentas de leitura disponíveis.
Informe revisão, ambiente e fontes examinadas; não presuma que uma mudança local foi publicada.

## Comparar intenção e evidências

Use decisões explícitas para estabelecer o requisito atual. Uma mudança aprovada pode substituir
um plano anterior; a data mais recente de um arquivo não basta. Preserve contradições abertas
em vez de escolher a versão que faz o trabalho parecer concluído.

Identifique a fonte oficial de requisitos e estado e diferencie registro vigente de histórico.

# Revisar alterações específicas

Use `tratar-revisao` para tratar comentários já recebidos e `examinar-arquitetura` para examinar
atrito estrutural do código existente sem depender de um diff. Este procedimento produz achados
sobre alterações específicas; não aplica correções por conta própria.

Fixe as revisões de base e de destino antes de ler. Diferencie mudanças commitadas de alterações
locais incluídas no pedido; um diff vazio entre commits não pode esconder edições não commitadas.
Use ferramentas de diff e histórico somente quando permitidas. Se o pedido proibir execução,
leia diretamente o diff e os arquivos fornecidos, sem invocar comandos de terminal.

Leia os requisitos e registros aplicáveis, os padrões do projeto, a arquitetura relevante e
as decisões existentes. Consulte requisitos apenas por meios permitidos. Se faltar acesso
ou documentação, declare o limite da comparação e continue a revisão dos padrões e do código.

# Tratar feedback de revisão

Leia o pedido, os comentários completos, a revisão a que se referem e o estado atual do código.
Identifique os requisitos e as decisões aplicáveis. Feedback é uma alegação a verificar,
inclusive quando veio de outro agente; não aceite nem descarte pelo nome ou modelo de quem escreveu.
Uma linha citada pode ter mudado desde a revisão: rastreie o comportamento atual antes de agir.

## Conferir cada item

Para cada comentário, entenda o problema alegado, confira os pontos de uso e verifique se a
sugestão corrige esse problema sem quebrar contratos existentes. Separe bug, preferência de
estilo, pergunta e mudança de escopo. Não aplique uma solução apenas porque o problema é real;
compare alternativas menores quando a sugestão introduzir custo ou incompatibilidade.
Confira condições e exceções do contrato inteiro, inclusive papéis privilegiados e entradas

# Verificar o aceite

Leia requisitos, tarefas, critérios, decisões, revisão fixada e achados anteriores.
Julgue apenas o escopo aprovado e os requisitos aplicáveis. Você precisa ser independente
da implementação; verificar o próprio trabalho não comprova aceite independente.

Use a versão autorizada vigente na fonte oficial do projeto, preservando a referência às
substituições. Uma mudança de critério ou método exige conferir a aplicabilidade das provas;
resultado de uma versão anterior não aprova automaticamente a nova. Relacione o resultado
às referências dos critérios existentes, sem criar outro registro concorrente de estado.

Quando a delegação estiver autorizada, use um contexto novo com o papel `evaluator`,
quando disponível. Forneça revisão fixada, passos de prova, instruções de execução
e limites de permissão. Siga `delegar` e relate configurações reais de modelo e ferramentas,

# Atualizar o harness de um projeto

Use quando o usuário pedir para trazer atualizações das skills ou do harness de origem para
um projeto. A origem padrão é [jordyfontoura/skills](https://github.com/jordyfontoura/skills),
salvo uma origem já configurada ou explicitamente escolhida pelo usuário.
Use Git, API ou ferramenta do GitHub disponível. Para uma origem privada, use o acesso
autenticado existente e não peça credenciais no texto da conversa. Se o acesso faltar,
informe o impedimento sem substituir a origem por um repositório parecido ou alterar o destino.

Registros com a origem anterior `jordyfontoura/harness` pertencem à mesma linhagem. Busque
versões novas em `jordyfontoura/skills`, nunca no repositório antigo, que está arquivado.
Se a revisão registrada for a indicada na seção 0.1.0 do CHANGELOG da origem, use a versão
0.1.0 como base: o conteúdo só difere na seção de origem do CHANGELOG. Para revisões anteriores, use o repositório antigo
como base só com acesso autenticado já disponível; sem ele, compare diretamente e trate as

# Configurar o harness

Leia manifestos, arquivos de dependências fixadas, CI e instruções existentes para encontrar
os comandos reais de instalação, execução, formatação, lint, tipos e testes. Preserve
verificações úteis. Se uma escolha de tecnologia impedir a configuração, pergunte por ela
em vez de inventar um sistema de dependências.

Use os scripts, o executor de tarefas e a CI existentes quando disponíveis. Mantenha os
comandos executáveis diretamente no repositório. Num projeto de documentação, use checagens
proporcionais de estrutura, links e metadados. Não adicione ferramentas de aplicação apenas
por causa do harness. Teste o validador com fixtures mínimas criadas pelo próprio teste,
separadas da verificação do repositório real, mantendo os casos que devem falhar, como links
quebrados. Assim, um documento novo não exige ampliar a cópia usada pelos testes.
Use `conhecer-ferramentas` para inventariar ferramentas e preparar faltantes quando essa instalação fizer

# Conhecer e preparar ferramentas

Identifique a intenção: explicar uma ferramenta, conferir o ambiente ou preparar ferramentas
para uma tarefa. Leia [tools.md](tools.md) apenas nas partes relevantes. Não transforme uma
pergunta explicativa em instalação nem tente instalar todo o catálogo.

## Explicar e escolher

Relacione a ferramenta à tarefa, ao sistema operacional e às opções já disponíveis. Explique
o que ela resolve, suas limitações e um exemplo concreto. Diferencie CLI, recurso nativo do
agente, servidor MCP e extensão. Respeite a preferência do usuário e as ferramentas exigidas
pelo ambiente; uma CLI não autoriza contornar restrições do provedor.

O catálogo é referência, não inventário vivo nem prova de disponibilidade. Para versões,

# Melhorar o harness a partir da sessão

Use a conversa, o diff relevante, os resultados das verificações e os registros existentes
para estabelecer o ocorrido. Separe a dificuldade observada da hipótese sobre sua causa.
Não inspecione transcrições privadas ou segredos para reconstruir uma sessão.

Para cada proposta, explique o incidente, a menor mudança que o evitaria e seu custo.
Prefira conectar uma verificação existente a acrescentar outra regra. Problemas de navegação
podem precisar de uma referência; erros mecânicos recorrentes, de uma checagem determinística;
decisões de julgamento, de um padrão curto. Remova orientação desatualizada ou duplicada
quando ela for a causa. Não transforme um caso isolado em política para todos os projetos.

Apresente apenas propostas que teriam mudado o resultado observado. Falta de verificações
é um achado, não autorização para alterar o harness. Aplique mudanças já autorizadas; nos

# Consultar o andamento

Responda à pergunta com o contexto e os últimos resultados disponíveis. Preserve o objetivo,
as decisões e a etapa autorizada. Uma consulta de andamento não cancela a execução, não muda
prioridades nem concede aprovação para uma ação que estava aguardando decisão.

## Consultar sem desviar

Na mesma conversa, responda quando o ambiente entregar a pergunta ao agente. A skill não
controla filas, pausas ou interrupções da ferramenta e não promete resposta simultânea à
execução. Depois do resumo, continue a etapa que estava em andamento e já autorizada.
Se o trabalho terminou ou aguardava aprovação, acesso ou outra condição de retomada,
informe isso e preserve esse estado; a pergunta não libera a espera nem inicia trabalho novo.

# Consultar especialistas

Identifique a pergunta, as restrições combinadas e o objeto da consulta: uma decisão, proposta
ou estado atual. Fixe a versão ou os materiais em análise. Leia as regras de comitê e as
instruções de especialistas existentes.
Sem proposta pronta, use o estado atual e a pergunta como objeto comum da consulta. Peça o
melhor argumento para manter esse estado, melhorias sustentadas e critérios de escolha;
não invente uma proposta aprovada nem trate a exploração como autorização para implementar.
Uma dúvida factual comum raramente exige conselho; investigue diretamente ou use `entrevistar`
para uma escolha que cabe ao usuário.

Adapte a pergunta comum à situação, sem exigir um formato diferente de relatório para cada caso:

- **Explorar melhorias:** examine o estado atual, o que preservar e as poucas mudanças de

# Delegar trabalho delimitado

Delegue apenas quando autorizado e quando houver uma parte independente, com dependências
satisfeitas, resultado e responsabilidade claros. Faça pequenas edições diretamente quando explicá-las custar tanto
quanto executá-las. Preserve os limites de permissão: revisão de código não autoriza execução,
edição nem novas delegações.

## Escolher trabalho e ferramentas

Se o destino tiver `.agents/models.toml`, consulte a política e o guia local, quando houver, antes de
selecionar o modelo. Identifique a responsabilidade: `orchestrator`, `planner`, `implementer`,
`reviewer`, `evaluator`, `representative` ou `council`, conforme a tarefa, ou uma responsabilidade
adicional configurada pelo projeto. A escolha explícita do usuário no pedido atual prevalece.
Sem política local, preserve a seleção do ambiente e do usuário. A resolução não exige scripts:

# Alinhar decisões

Para rodadas respondidas em arquivo Markdown, use
`entrevistar-por-arquivo`. Esta skill conduz o alinhamento pela conversa.

Leia o pedido, os arquivos relevantes, as decisões existentes e a última passagem de contexto.
Separe fatos que as ferramentas podem esclarecer de escolhas que cabem ao usuário.
Investigue os fatos primeiro.

Antes de perguntar, procure respostas nos documentos, na conversa e nas fontes conectadas
disponíveis. Reutilize respostas já estabelecidas com seu escopo e sua origem. Se houver
conflito, explique-o e pergunte apenas o necessário para resolvê-lo. Falta de acesso não é motivo
para exigir que o usuário repita todos os fatos. Não deduza dados pessoais ou consentimento
a partir de exemplos.

# Alinhamento assíncrono por arquivo

Use este modo quando o usuário quiser responder perguntas em Markdown, no seu tempo, e
retomar com o agente depois. Aplique os critérios de `entrevistar`: investigar fatos disponíveis,
preservar escolhas já feitas e perguntar só o que muda o resultado. Escreva as rodadas em
português brasileiro, salvo pedido diferente, usando o vocabulário do projeto.

## Preparar o alinhamento

Leia os documentos, decisões e perguntas existentes antes de criar arquivos. Reutilize o
formato que o projeto já adota. Se não houver, copie e preencha o
[modelo](alignment.template.md) na documentação do projeto, por exemplo em
`docs/alignment/<tema>.md`. O caminho é uma sugestão, não uma estrutura obrigatória.
Substitua as perguntas de exemplo por perguntas reais antes de apresentar o arquivo.

# Pera aí, explica de novo

Retome o ponto que não ficou claro. Leia a mensagem anterior e o contexto necessário para
entender a dúvida. Se ela aponta um trecho, concentre a resposta nele. Não repita a mesma
explicação apenas trocando palavras nem peça que o usuário explique tudo de novo.

Explique em português brasileiro, salvo pedido de outro idioma. Comece pelo que faltou para
entender o ponto, recuperando contexto apenas quando necessário. Use palavras familiares e,
quando ajudar, um exemplo do próprio projeto. Prefira frases curtas e uma ideia por frase.
Ajuste o detalhe à pergunta, sem
transformar uma dúvida pontual em uma aula sobre o sistema inteiro.

Escolha a forma da explicação pelo tipo de dúvida; combine formas quando necessário, sem
transformá-las em seções obrigatórias:

# Escrever com clareza

Textos genéricos e repetitivos dificultam a leitura. Cada frase deve dizer algo específico,
em palavras simples, uma vez.

Aplique ao redigir e editar textos para outras pessoas: títulos e corpo de documentos,
tarefas, PRs, e-mails e mensagens. Títulos e descrições curtos também merecem revisão de clareza.
Conversa de rotina não exige anunciar a skill. Clareza não determina a voz pessoal do usuário;
preserve amostras fornecidas e pergunte apenas quando uma preferência ausente mudar o resultado.

## Como aplicar

1. Leia o texto inteiro ou as instruções de redação. Identifique público, finalidade, idioma e tom.
2. Localize os sinais listados abaixo.

# Escrever um objetivo de execução

Entregue um texto pronto para colar, compatível com o limite do destino: menos de 4.000 caracteres
quando ele for desconhecido. Escrever o objetivo não inicia uma execução nem autoriza ações externas.

Inclua resultado, repositório, requisitos ou caminhos relevantes, critérios no escopo e como
consultá-los. Nomeie a etapa inicial e a última passagem de contexto. Uma continuação segue
essa etapa sem reabrir escolhas resolvidas. Aponte para requisitos em vez de copiar toda a especificação.

Descreva a condição observável de conclusão: critérios comprovados pelos métodos combinados,
verificações relevantes passando e aceite independente, se exigido. Implementação e avaliação
independente são distintas. Avaliação ou acesso ausentes continuam sem prova.

Declare limites de atuação, arquivos e worktree sob responsabilidade, exclusões e decisões

# Preservar o contexto para retomada

Leia o trabalho atual e a passagem de contexto mais recente. Resuma o que outra sessão precisa
para continuar sem repetir a investigação, abrindo pelo estado atual:

- Tarefas e processos ativos, com identificador, responsável e como conferir o estado ou
  receber o resultado.
- Objetivo, escopo combinado e links para o plano ou os requisitos.
- Branch e worktree, base fixa do diff, commits, arquivos sob sua responsabilidade e alterações
  ainda não commitadas, com explicação.
- O que foi comprovado, com comandos, resultados exatos e a revisão a que se aplicam, e o que
  continua sem prova.
- Próxima etapa exata (`revisar`, `implementar`, `verificar-aceite`, `especificar` ou outra atividade nomeada)
  e primeira ação concreta.

# Pesquisar com fontes

Ao usar esta skill, consulte a internet com as ferramentas disponíveis. Conhecimento do modelo,
arquivos locais e memória da conversa ajudam a orientar a pesquisa, mas não substituem essa
consulta. Não apresente uma resposta de memória como pesquisa realizada.

## Delimitar a pergunta

Identifique o que a pesquisa deve responder ou ajudar a decidir, o público, o contexto e os
limites relevantes de idioma, região, período ou versão. Leia os materiais locais necessários
para relacionar os achados ao pedido. Pergunte apenas quando uma escolha ausente mudar o
resultado; explicite suposições razoáveis e prossiga nos pontos independentes.

Transforme o pedido em perguntas investigáveis. Para melhorar algo existente, examine também

# Propor antes de executar

Use quando o usuário pedir uma proposta antes da ação. A menção a esta skill define uma etapa
de explicação e revisão, mesmo se o restante do pedido descrever algo a implementar.
Não transforme todo pedido comum numa aprovação obrigatória; este modo atende à espera
solicitada pelo usuário.

## Entender sem alterar

Leia o pedido, as instruções relevantes, as decisões existentes e os arquivos necessários
para propor algo viável. Use ferramentas de leitura e investigação dentro do escopo permitido.
Não peça ao usuário fatos que você pode conferir. Se uma escolha importante continuar aberta,
explique a dúvida e as opções; use os princípios de `entrevistar` sem reiniciar decisões resolvidas.