zehuichan/vibe-harness

Padrão de documentação

Faça cada página pesquisável, legível para iniciantes e exata o suficiente para agentes e mantenedores. Os níveis, regras de escrita, orçamentos e a checklist de slop estão em docs/AGENTS.md; este skill possui o fluxo de trabalho para aplicá-los. Preserve um dono por fato: fonte, testes, catálogos gerados, READMEs, guias e Notas de Agente cada um mantém seu próprio tipo de verdade. Isto é orientação, não uma checklist.

Fluxo de trabalho

Siga esta sequência para cada escopo solicitado. Mantenha o caminho do leitor comum breve, mas não exclua falhas, propriedade, limitações ou outros contratos necessários para reduzir palavras.

1. Leia os arquivos AGENTS.md raiz e da subárvore, docs/AGENTS.md, a página alvo, sua fonte e testes, e seu dono de navegação.
2. Classifique a página por um trabalho primário e leitor: início rápido, guia de tarefas do usuário, tutorial do contribuidor, visão geral da arquitetura, referência do módulo, referência gerada, instrução do agente, registro de decisão ou rascunho.
3. Coloque a página em seu dono mais próximo. Mantenha contratos do módulo junto ao código do módulo; use docs/ para material de aprendizado entre módulos, de usuário, de desenvolvedor e de arquitetura.
4. Defina o estado inicial do leitor, resultado observável, falha provável, caminho de recuperação e próxima profundidade útil antes de escrever detalhes.
5. Escreva na ordem dada por estrutura de página: título, Resumo, conteúdo, conteúdo voltado ao usuário, conteúdo voltado ao desenvolvedor, Exploração Adicional opcional.
6. Quando o perfil habilitar surfaces.bilingual-docs, atualize a contraparte na mesma passagem e mantenha cabeçalhos, listas, tabelas, código e links alinhados linha por linha.
7. Verifique cada afirmação contra código, testes, geradores, metadados de pacote ou um dono de decisão atual e execute as operações que a página instrui (veja o procedimento de verificação de fatos abaixo). Atualize o dono antes de qualquer artefato derivado.
8. Execute commands.docs-check e git diff --check do perfil, então releia o diff completo uma vez para correção e uma vez para brevidade e ajuste.

Procedimento de verificação de fatos: teste, não assuma

A documentação afirma como o produto se comporta hoje, e a única evidência admissível para uma afirmação de operação é tê-la executado. Isto se aplica a cada nova página e cada novo parágrafo que afirma um comando, default, erro, saída ou diferença de plataforma.

1. Classifique o assunto antes de escrever orientações de instalação ou uso. Leia os fatos (manifestos, pontos de entrada, exportações), não o nome da pasta. Uma biblioteca, um plugin, um CLI e um serviço cada um tem um caminho de uso diferente; nunca copie orientação escrita para outro tipo.
2. Execute cada operação afirmada contra o checkout atual. Execute cada comando, trecho de configuração e exemplo exatamente como a página o mostrará; anote apenas o que você observou, incluindo avisos e modos de falha. Se uma afirmação depender de credenciais ou uma rede que você não possui, diga isso e nomeie o dono da verificação em vez de afirmar o comportamento.
3. Exclua o que você não pôde reproduzir. Nunca carregue um comando, campo, default ou comportamento da memória, analogia ou de um README vizinho. Quando uma afirmação falha ao reproduzir, corrija a afirmação, não o teste.
4. Verifique documentação antiga contra o branch padrão mais recente. Antes de revisar uma página existente, busque e compare com o branch padrão; corrija declarações desatualizadas contra o código, não contra a prosa antiga.

Regras de voz

• Resumo diz o que o assunto faz. As seções de Resumo e voltadas ao usuário descrevem o que um leitor pode fazer com o assunto (resultados, quando escolhê-lo, custo principal), nunca sua identidade interna ou registros. Omita identificadores de fonte a menos que o leitor os use diretamente em configuração, um comando ou uma API pública.
• Seções de desenvolvedor explicam, nunca enumeram. O detalhe do desenvolvedor cobre o conceito de design, arquitetura e fluxo de dados aproximado, suficiente para entender como funciona, e vincula o código para detalhes exatos. Sem catálogos completos de API, listas de colunas ou reafirmação de documentação de API.
• Apenas estado atual. Documentação comum descreve a base de código atual; o histórico pertence a Notas de Agente, post-mortems, notas de lançamento e guias de atualização.
• Inglês técnico controlado. Dê a cada frase um ator explícito e uma ação principal quando a ambiguidade puder mudar o comportamento; reutilize um termo por conceito; divida instruções empilhadas; preserve modalidade e exceções. Veja estrutura de página.

Critérios de qualidade

• Breve: o caminho comum contém apenas fatos necessários para seu resultado; a verdade exaustiva está a um link ou camada de detalhe de distância.
• Intuitivo: pré-requisitos precedem conceitos dependentes, uma próxima ação é óbvia e cabeçalhos usam termos que os leitores pesquisam.
• Amigável: os leitores podem reconhecer sucesso, entender risco antes de agir, recuperar-se de falha provável e escolher se vão mais fundo.
• Preciso: cada afirmação durável tem um dono e um caminho de verificação proporcional ao seu risco.
• Legível por agente: cabeçalhos, âncoras, terminologia e propriedade estáveis suportam recuperação direcionada sem carregar todo o corpus.
• Completo para novatos: um engenheiro sem contexto do repositório pode reconstruir a arquitetura ou funcionalidade relevante através de três a cinco páginas vinculadas.

Não aplique um limite universal de palavras a referências exaustivas; meça o comprimento do caminho de entrada, material não relacionado escaneado por consulta e a maior seção, e divida por um dono de domínio existente quando o custo de recuperação for alto.

Audite o corpus

Aplique a ordem de autoria de docs/AGENTS.md a cada documento voltado a humanos no escopo (não a Notas de Agente): localize o documento e declare seu assunto; defina seu detalhamento permitido e mova explicações mais profundas para descendentes proprietários; classifique tutorial ou referência pelo uso pretendido, não pelo caminho; divida formas mistas substanciais. Uma movimentação é atômica com cada link de entrada reparado na mesma alteração; catálogos gerados nunca são editados manualmente.

Em seguida, caça a checklist de slop em docs/AGENTS.md, sondas mais baratas primeiro: use trim-cot-leakage para vazamento de transcrição de raciocínio, pesquise frases distintivas para regras duplicadas, substitua catálogos escritos à mão por seus donos autoritativos e remova especulação de Notas de Agente implementadas. Se remover prosa alteraria o comportamento prometido em vez de sua explicação, proponha a mudança de comportamento primeiro (veja find-simplifications). Mantenha cada regra que suporta carga, preferencialmente como uma a três linhas mais um link para sua justificativa.

Referências detalhadas

• Estrutura de página e estilo: ordem da página, progressão de seções, dobramento, inglês técnico controlado e ênfase.
• Critérios de revisão: teste do novato, revisão de evidência e revisão de README.

Use prose-standard para cobertura de contrato no nível da frase e julgamento editorial.