EvolveHQ/docflow

add-convention

Adiciona uma convenção — mas somente após avaliar se ela deve existir e onde pertence. Este skill é um guardião e um roteador, não um estenógrafo.

Etapa 0 — Pré-condições e contexto

1. Confirme que o repositório foi inicializado.
2. Leia CONVENTIONS.md e AGENTS.md na íntegra para detectar sobreposição com regras existentes e julgar a adequação.

Etapa 0.5 — Avaliação (executar primeiro)

Execute o protocolo de avaliação compartilhada; as perguntas de triagem (Etapa 1) e roteamento (Etapa 2) são feitas dentro dele:

• Reutilize respostas fornecidas primeiro. Trate escolhas aplicáveis já fornecidas na solicitação ou nesta sessão, incluindo profundidade, como respondidas. Resuma-as sem perguntar novamente; padrões nunca substituem escolhas explícitas. Se toda escolha material for fornecida, prossiga. Pergunte apenas sobre uma escolha material ausente ou conflitante. Uma preferência de repositório sozinha não é uma resposta atual ou uma concessão de execução.

• Seletor de profundidade para escolhas não resolvidas. Se a profundidade não for fornecida e escolhas permanecerem, pergunte quão profunda esta avaliação deve ser: express — toda escolha assume seu padrão recomendado; apenas perguntas sem um padrão derivável (os itens essenciais de texto livre) ainda são feitas; guided — apenas as perguntas marcadas como de alto impacto abaixo, mais os itens essenciais de texto livre; full — toda pergunta abaixo. Se o CONVENTIONS.md do repositório registrar uma Assessment depth:, pré-selecione-a como a opção recomendada ao perguntar; uma profundidade registrada nunca é aplicada silenciosamente. Caso contrário, recomende full quando a solicitação chegou com pouco ou nenhum contexto e express quando já estiver totalmente especificada. A qualquer pergunta o operador pode responder "padrões daqui em diante" ou "vá mais fundo"; honre a troca imediatamente.

• Faça perguntas uma de cada vez, cada uma com uma opção recomendada e um motivo de uma linha; aguarde cada resposta.

• Use seleção estruturada (escolha única ou múltipla). Se o host expuser uma ferramenta de pergunta de escolha única/múltipla estruturada, use-a e marque a opção recomendada; caso contrário, liste opções A/B/C em texto simples e nomeie a recomendada. Use texto livre apenas onde um conjunto enumerável for impossível (ex.: a redação exata).

• O operador decide. Nunca prossiga além de uma pergunta sem uma resposta, e nunca adivinhe o escopo quando invocado sem contexto.

Perguntas (pule qualquer uma que a solicitação já responda):

1. Vale a pena codificar? — sim (recorrente, estável, testável) ou não (pontual, duplicada, propensa a mudanças, vaga). Recomendado: conforme a triagem da Etapa 1; esta pergunta bloqueia o restante. (Alto impacto — perguntada em guided.)
2. Local — regra rígida no AGENTS.md / orientação no CONVENTIONS.md / termo no GLOSSARY.md / na verdade é uma decisão (repassar para o skill new-adr). Recomendado: conforme a natureza da regra (veja Etapa 2). (Alto impacto — perguntada em guided: o local errado gera retrabalho para mover.)
3. Aplicar na verificação de gate? — sim / não. Recomendado: não, a menos que a regra seja mecanicamente verificável.
4. Redação — texto livre (a declaração da regra em si; perguntada em toda profundidade).

Etapa 1 — Avaliar: vale a pena codificar isso?

Aplique a triagem. Recomende contra adicionar quando:

• Já estiver coberta (explícita ou implicitamente) por uma convenção existente — aponte para ela em vez de duplicar.
• For uma decisão pontual, não recorrente — codificá-la adiciona ruído.
• For propensa a mudanças — regras prematuras viram entulho obsoleto.
• For muito vaga para ser testável ou acionável como escrita.

Recomende a favor de adicionar quando for uma decisão recorrente cuja ambiguidade causa retrabalho, for estável e puder ser declarada de modo que um agente possa segui-la sem interpretação adicional. Apresente sua recomendação e o motivo antes de fazer qualquer coisa.

Etapa 2 — Roteamento: onde pertence?

Decida o local e explique a escolha:

• Regra rígida que os agentes devem obedecer → um item em AGENTS.md §Regras rígidas, com o conteúdo em CONVENTIONS.md. Use para restrições inegociáveis.
• Orientação de autoria/processo → uma seção em CONVENTIONS.md. Use para "como fazemos as coisas" que informa mas não bloqueia.
• Termo/definição compartilhados → GLOSSARY.md (crie-o se estiver ausente — adicionar o primeiro termo ativa a camada de glossário; coloque-o na raiz do artefato registrada). Leia a seção CONVENTIONS.md §Glossário e inspecione a regra que ele realmente declara; a estrutura canônica é um cabeçalho H1 opcional e prosa introdutória opcional, então exatamente uma tabela Markdown de duas colunas cujo cabeçalho é Term | Definition. Cada termo é sua própria linha. Nunca registre um termo como um cabeçalho, um item ou um parágrafo, e nunca adicione uma segunda tabela ou uma forma de coluna diferente. Uma seção §Glossário que declara uma convenção de glossário mais antiga ou não relacionada não é adoção desta tabela: use a forma canônica e ofereça a migração de regra-e-arquivo separadamente consentida do skill de auditoria em vez de copiar a forma antiga. Um GLOSSARY.md ausente permanece um estado válido; este skill cria um apenas porque um termo está sendo realmente adicionado.
• Na verdade é uma decisão, não uma convenção (uma escolha arquitetural, de produto ou tecnológica com alternativas e consequências) → isso é um ADR. Pare e ofereça o skill new-adr; não enterre uma decisão em CONVENTIONS.

Se uma convenção for uma regra de triagem/processo (ex.: como o trabalho recebido é triado), prefira CONVENTIONS.md com um item de regra rígida em AGENTS.md apenas para as partes que são inegociáveis.

Etapa 3 — Redigir e confirmar

Redija a redação exata para o arquivo de destino. Mantenha-a concisa, testável e no idioma do repositório. Mostre o diff. Confirme antes de escrever.

Etapa 4 — Escrever e commitar

Aplique as edições. Se uma convenção se elevar a uma regra rígida, garanta que AGENTS.md e CONVENTIONS.md permaneçam consistentes. Commit convencional (docs: ...); nenhum ADR tocado significa que nenhum rodapé Rationale: é necessário, mas adicione um se o contrato do repositório o solicitar para alterações de convenção.

Adicionando ou estendendo um glossário. Use a estrutura canônica definida abaixo e as verificações de regra declarada; a forma não deve divergir entre execuções.

• De onde a regra vem. Se CONVENTIONS.md não tem uma seção §Glossário (um repositório legado que a antecede, ou uma camada ativada antes da regra ser registrada), recorra à forma canônica padrão do produto acima: cabeçalho opcional # Glossary e prosa introdutória, então uma tabela Term | Definition. Não invente uma forma diferente para aquele repositório e não edite silenciosamente convenções não relacionadas.
• Lendo a regra declarada. Quando uma seção §Glossário existe, leia o que ela realmente declara. Se descrever a tabela canônica de duas colunas Term | Definition, siga-a e altere-a apenas sob solicitação explícita. Se declarar uma convenção de glossário diferente ou mais antiga (itens, prosa, outra forma de coluna), o repositório não adotou esta tabela: não copie a forma antiga e não reescreva silenciosamente a regra. Use a forma canônica para o termo e ofereça a migração do skill de auditoria, que cobre a regra e o arquivo juntos como um diff separadamente consentido.
• Registrando a convenção. Quando uma seção §Glossário está ausente, ofereça — como sua própria edição confirmada, separada do termo sendo adicionado — registrar uma seção ## Glossary em CONVENTIONS.md declarando a forma realmente usada. Mostre esse diff e escreva-o apenas se o usuário aceitar; nunca reescreva ou reordene outras seções de CONVENTIONS.md para abrir espaço, e se o usuário recusar, mantenha o glossário canônico mas deixe CONVENTIONS.md inalterado.
• Criando o arquivo. Escreva o cabeçalho opcional # Glossary e qualquer prosa introdutória curta que o repositório precisar, então a única tabela de duas colunas com cabeçalho Term | Definition e o novo termo como sua primeira linha. Não invente termos de espaço reservado.
• Estendendo um arquivo existente. Preserve o cabeçalho, a prosa introdutória, a ordem de entrada e cada linha existente byte por byte. Anexe o novo termo como uma nova linha; nunca reconstrua, reordene ou reformate o arquivo, e nunca introduza uma segunda tabela.
• Âncoras. Se a linha do novo termo for acessível a partir de uma âncora de cabeçalho que um link recebido já usa, mantenha essa âncora na linha em vez de remover o destino; se a âncora não puder ser preservada, pare e sinalize em vez de adivinhar.
• Preserve o significado. Mantenha a grafia, aliases, links e código inline do termo exatamente como fornecidos. Escape uma pipe literal como \|. Se uma definição for genuinamente multilinha, mantenha-a em uma célula com <br> para a quebra forçada em vez de derramar em linhas extras.
• Duplicatas e ambiguidade. Se o termo já existir, mostre as definições existente e proposta e pergunte se deve atualizar ou deixar a linha existente. Nunca mescle, substitua ou adicione silenciosamente uma segunda linha para o mesmo termo, e nunca adivinhe uma definição.
• Arquivo não canônico. Se o GLOSSARY.md existente for itens, prosa, cabeçalhos ou uma forma mista, não anexe uma linha concorrente e não reescreva o arquivo como efeito colateral de adicionar um termo. Exponha a estrutura não canônica e ofereça a migração consentida do skill de auditoria; aplique-a apenas se o usuário aceitar o diff concreto. Uma migração recusada deixa o arquivo como o usuário o mantém.

Nomeie a regra e a propagação realizada; liste repositórios não atualizados.

Relatório de fechamento

Termine toda execução, incluindo execuções bloqueadas, falhas e interrompidas, com uma seção intitulada exatamente Status at a glance, contendo estes três rótulos:

• This run: apenas ações realmente tentadas e seus resultados; cite a saída exata e o código de saída de cada verificação de gate, incluindo timeouts ou interrupções.
• Overall: implemented, partially verified, verified, blocked, failed ou unknown. Uma subetapa bem-sucedida não é uma aprovação geral; evidência incompleta ou ausente nunca se torna sucesso.
• Yet to do: toda ação restante, achado não resolvido, verificação, limpeza ou entrada necessária. Escreva None apenas quando toda a tarefa estiver verificavelmente completa; nunca omita trabalho porque um orçamento terminou.

Mensagens de progresso rotineiras não precisam de bloco. Mantenha os resultados finais breves e distinga trabalho preparado em um PR de trabalho confirmado como enviado.