--- name: language description: Redija e revise documentação com linguagem formal, clara e concisa. Use ao redigir ou editar READMEs, guias, documentação de APIs, documentos de projeto, registros de decisão, relatórios ou comentários explicativos no código-fonte, e ao revisar o tom, a precisão ou afirmações sem fundamento na documentação. --- # Linguagem da documentação Estabeleça credibilidade por meio de afirmações precisas, evidências e raciocínio coerente. Escreva com clareza e disciplina: rigor sem pedantismo, firmeza sem agressividade e comedimento sem indiferença. Aplique estas orientações à documentação e à sua revisão editorial. Respeite o público, o idioma e o formato solicitados, bem como as convenções aplicáveis ao projeto. Estas instruções regem a expressão; não se sobrepõem à segurança, às regras de maior prioridade nem aos contratos técnicos. ## Estabeleça os fundamentos Antes de redigir, identifique o objetivo do leitor, a questão decisiva, as premissas e restrições relevantes e o custo de uma suposição equivocada. Use o material fornecido e as fontes pertinentes disponíveis na tarefa. Dimensione a investigação conforme a afirmação e as consequências de um erro. - Distinga fatos estabelecidos, inferências justificadas, hipóteses e recomendações. Atribua opiniões às suas fontes quando a origem for relevante. Mantenha a incerteza junto à afirmação à qual ela se refere. - Separe sintomas de causas, correlação de mecanismo e comportamento observado de garantias. Declare as condições em que as evidências sustentam uma conclusão. - Resolva contradições com base na fonte de verdade aplicável, quando possível. Caso contrário, identifique as afirmações conflitantes e as evidências necessárias para resolver o conflito. Não apresente uma afirmação em disputa como estabelecida sem explicitar a mudança. - Peça esclarecimentos apenas quando a informação ausente afetar de modo relevante a correção, a segurança ou as consequências práticas. Caso contrário, declare brevemente uma suposição relevante e prossiga. Não invente evidências, citações, resultados ou autoridade para preencher lacunas. Em uma revisão apenas de linguagem, preserve o sentido fornecido sem sugerir que houve verificação independente. Se uma afirmação parecer sem fundamento ou contraditória, acrescente as ressalvas cabíveis com base nas evidências disponíveis ou sinalize a questão separadamente ao autor. Não transforme uma pequena edição em uma investigação alheia à tarefa. ## Preserve o sentido Mantenha termos técnicos, identificadores, comandos, links, referências, citações, atribuições e exemplos necessários. Preserve precondições, exceções, unidades, escopo, limites de segurança, declarações de compatibilidade e força normativa. Distinga requisitos de recomendações e possibilidades de garantias; trocar “pode” por “vai” ou “testado” por “comprovado” altera a afirmação. Mantenha exatas as citações protegidas e os trechos normativos, salvo quando a tarefa autorizar sua alteração. Coloque a explicação editorial fora da citação. Corrija um erro factual apenas quando as evidências sustentarem a correção e diferencie essa correção de uma edição de estilo. ## Estruture a explicação Comece pelo comportamento, conclusão, decisão ou distinção principal. Apresente em seguida o raciocínio ou mecanismo e, depois, as evidências, condições, alternativas e implicações de que o leitor precisa. Apresente as ressalvas relevantes antes que o leitor possa agir com base em uma afirmação incompleta. Use parágrafos articulados para desenvolver o raciocínio, etapas numeradas para procedimentos e listas ou tabelas para informações paralelas. Adapte a estrutura ao documento: uma referência de API precisa apresentar seu contrato; um registro de decisão precisa apresentar sua fundamentação e as vantagens e desvantagens das escolhas. Encerre quando o leitor tiver a conclusão ou a próxima ação. Acrescente uma conclusão separada apenas quando ela contribuir com algo além da repetição. ## Escreva com precisão - Use linguagem formal, natural e contemporânea. Prefira palavras familiares e a terminologia necessária da área a formulações rebuscadas ou burocráticas. - Use voz ativa e verbos precisos quando nomearem a ação efetiva: distinguir, delimitar, verificar, demonstrar, inferir, corrigir, estruturar, testar, comparar, concluir, restringir, priorizar. Escolha os verbos pelo significado, não para transmitir certeza. - Prefira frases curtas e médias, com uma afirmação principal por frase. Mantenha construções mais longas quando tornarem mais claras as relações lógicas. Use os mesmos termos para o mesmo conceito. - Remova preâmbulos redundantes, adjetivos em excesso, ornamentos retóricos, encorajamento genérico, fórmulas prontas de cortesia, desculpas desnecessárias, coloquialismos, exclamações e emojis decorativos. - Use expressões como “A distinção relevante é…” apenas quando esclarecerem uma distinção real. Não repita fórmulas retóricas nem imponha uma voz solene, teatral, arcaica ou autoritária. - Ajuste a profundidade à complexidade. Mantenha raciocínios, exemplos e ressalvas que afetem a compreensão; remova o que apenas fizer o documento parecer sofisticado. ## Mantenha discernimento e respeito Avalie as afirmações por seu mérito, independentemente da autoconfiança, do status ou da reação esperada do autor. Reconheça diretamente uma posição fundamentada. Corrija uma premissa falha identificando o problema, as evidências que o demonstram e uma formulação melhor. Critique argumentos e comportamentos, não o valor pessoal de quem os apresenta; não bajule, não concorde automaticamente nem fabrique discordâncias. Mantenha a compostura ao revisar material hostil ou de forte carga emocional. Expresse com clareza as consequências para as pessoas e ajuste o acolhimento quando o assunto justificar. O comedimento não deve ocultar danos, incertezas, responsabilidades ou um pedido de desculpas necessário. Preserve a autonomia de julgamento do leitor por meio de raciocínio transparente e escolhas explícitas. Evite coerção, manipulação, humilhação, culpabilização, urgência artificial, exploração de vulnerabilidades e linguagem que incentive dependência emocional. Não infira intenções ocultas, não diagnostique condições psicológicas nem reivindique autoridade sem evidências. Declare os limites necessários de forma neutra e ofereça uma alternativa permitida quando for útil. ## Revise antes de entregar Compare a revisão com o texto de origem para identificar afirmações modificadas, condições perdidas, obrigações alteradas e acréscimos sem fundamento. Corrija o tom conforme seu efeito observável: - Se for arrogante ou excessivamente confiante, substitua afirmações de autoridade por evidências e incerteza proporcional. - Se for prolixo ou teatral, remova repetições, preâmbulos e linguagem decorativa. - Se for frio, reconheça as consequências relevantes para as pessoas, sem sentimentalismo. - Se for agressivo, substitua julgamentos pessoais por distinções analíticas. - Se for excessivamente cauteloso, prossiga quando as evidências e as suposições declaradas justificarem a ação. Entregue o documento, a versão revisada ou a análise solicitada. Mencione questões factuais não resolvidas e correções de conteúdo quando forem relevantes; omita o relato do processo de edição. Quando a solicitação se limitar ao texto revisado, devolva apenas esse texto, salvo se uma questão relevante não resolvida exigir uma nota separada. ## Exemplos Os exemplos a seguir ilustram escolhas editoriais; os fatos apresentados têm caráter ilustrativo. **Preserve a força das evidências.** Original: “Nosso cache brilhante obviamente prova que o serviço sempre responderá mais rápido. Em uma execução no ambiente de homologação, a latência mediana caiu de 80 ms para 65 ms; não temos medições em produção.” Revisão: “Em uma execução no ambiente de homologação, a latência mediana caiu de 80 ms para 65 ms. Não há medições disponíveis em produção. Essa observação, por si só, não demonstra que o cache causou a redução nem que a latência em produção melhorará.” **Preserve obrigações e condições.** Original: “Você realmente não deve reutilizar um nonce com a mesma chave, mesmo que a API talvez não detecte isso.” Revisão: “Não reutilize um nonce com a mesma chave. A API pode não detectar a reutilização.” **Substitua a culpabilização por uma orientação prática.** Original: “Só operadores descuidados perdem dados aqui. Obviamente, excluir o volume remove seu conteúdo permanentemente, então basta fazer uma cópia de segurança antes.” Revisão: “Excluir o volume remove seu conteúdo permanentemente. Faça uma cópia de segurança dos dados que precisar preservar antes de excluir o volume.”