Ephasme/refine-document

Refinar Documento

Pegue um documento e produza uma versão que um leitor sem histórico com o projeto possa usar: livre de legado, factual, conciso, organizado e moldado para o leitor declarado.

Quatro passagens, ordem fixa, depois uma verificação de validação. Tudo que for removido é escrito em um arquivo de registro, para que uma decisão errada seja recuperável.

Invocação

refine-document <caminho> [--target=agent|human] [--no-record]

Flag	Padrão	Efeito
--target	agent	Para qual leitor a última passagem otimiza. Muda o documento, não apenas o tom — veja Passagem 4.
--no-record	desligado	Pula o arquivo de registro. Remoções tornam-se irrecuperáveis, exceto pelo controle de versão.

Antes de tocar no arquivo:

1. Confirme que a solicitação nomeia este documento. Isso reescreve o arquivo do usuário no local.
2. Confirme que o arquivo está rastreado e limpo no controle de versão. Se não estiver, diga isso e obtenha uma autorização explícita — sob --no-record esse é o único caminho de recuperação restante.
3. Informe o alvo com o qual está executando em sua primeira mensagem, inclusive quando for o padrão. Um padrão silencioso é como um documento acaba moldado para o leitor errado.
4. Múltiplos documentos: execute este procedimento uma vez por documento, um subagente cada onde subagentes estiverem disponíveis, passando o mesmo alvo e flags para todos. Um subagente é dono de exatamente um arquivo.

Saídas

Saída	Caminho	Conteúdo
Documento refinado	o caminho original, no local	apenas estado atual, moldado para o alvo
Registro	{nome}.changelog.md, mesmo diretório	tudo removido, na íntegra, localizado — anexável entre execuções
Relatório	sua resposta	veja Relatório

Ordem das passagens

Execute as passagens nesta ordem, como quatro leituras separadas do documento. Cada uma encolhe a entrada para a próxima, e fora de ordem elas se desfazem — comprimir prosa que a passagem 1 iria deletar desperdiça trabalho, e organizar antes de comprimir organiza preenchimento.

1. Remover legado — remova tudo que só faz sentido como referência ao passado.
2. Factual — toda afirmação sobrevivente é verificada, citada ou marcada.
3. Conciso — um fato, um lugar, forma mais curta que mantém o fato.
4. Organizar — crítico primeiro, depois a forma do alvo.

Passagem 1 — remover legado

SUBSKILL OBRIGATÓRIA: use strip-legacy-content para esta passagem. Ela é dona da taxonomia de legado, da regra de remover-não-reescrever, e do formato {nome}.changelog.md que esta skill também escreve. Mapeie --no-record para seu --no-changelog.

Quando essa skill não estiver disponível, remova: narrativas de histórico e evolução, registros de decisão e ADRs, avisos de descontinuação, guias de migração e atualização, changelogs incorporados e notas de versão, seções de compatibilidade retroativa, alternativas rejeitadas, comentários datados, seções substituídas. Remova os trechos; não reescreva a prosa sobrevivente — as passagens 2-4 o farão.

A regra do recurso obsoleto. Um recurso marcado como obsoleto não é automaticamente legado. Aplique este teste e registre qual caminho você seguiu:

O recurso tem um uso que não seja "suportar o sistema antigo"?

• Não — ele existe apenas para compatibilidade retroativa. Remova o recurso e seu aviso.
• Sim — é comportamento atual. Mantenha-o, remova a linha do tempo de remoção e o enquadramento "desde v1", e sinalize-o no registro.

Passagem 2 — factual

Toda afirmação que o documento faz é uma declaração, incluindo as que ele herdou. Classifique cada uma e tome a ação correspondente. Não há quinta opção.

Classe	Sinal	Ação
Verificável, artefato acessível	comportamento, flags, padrões, caminhos, comandos, chaves de configuração, e você pode ler o código, o config ou o --help	Verifique. Verdadeiro: mantenha. Falso: corrija.
Verificável, artefato inacessível	as mesmas afirmações, sem repositório, sem binário e sem documentação para verificar	Mantenha a afirmação exatamente como a fonte a declara, sem marcação, e liste-a no relatório como não verificada.
Com fonte externa	padrões, comportamento de protocolo, comportamento de produto de terceiros, suporte de versão	Cite a fonte primária inline com sua data ou versão. Sem fonte aceitável: corte a afirmação.
Comparativa ou promocional	"10x mais rápido", "melhor da classe", "fulgurante", "elegante", "a maioria dos engenheiros concorda", e qualquer comparação cujo outro termo não seja parte do sistema atual ("mais leve que Kafka")	Corte, a menos que exista uma medição citável — então declare a medição e sua fonte. Mantenha o fato sobrevivente: "enfileira trabalhos com Redis Streams".
Inverificável e perigosa	uma afirmação não verificada sobre a qual um leitor poderia agir de forma irreversível: perda de dados, gastos, credenciais, um comando destrutivo, um limite de segurança	Mantenha, marque como [não-verificado] no documento e liste no relatório.

O marcador é para perigos, não para proveniência. Um documento sobre um artefato que você não pode acessar é principalmente afirmações não verificadas, e marcar cada uma ensina o leitor a pular o marcador. Proveniência não verificada pertence ao relatório e ao registro; [não-verificado] no documento é reservado para afirmações cujo fracasso o leitor não pode desfazer. Se mais de um punhado de marcadores sobreviver no documento, você classificou proveniência como perigo — reclassifique.

Nunca invente um fato que o documento fonte não tinha. Nem um local de configuração, nem um padrão, nem um formato de arquivo, nem um pré-requisito — nem mesmo um que seja quase certamente verdadeiro. Um fato inferido declarado de forma plana é indistinguível de um verificado, e esta passagem é a única coisa entre o leitor e uma resposta errada confiante. Se a fonte é silenciosa, o documento refinado é silencioso.

Nunca suavize uma afirmação sem fonte em uma mais vaga. "Aproximadamente 10x mais rápido" reescrito como "muito rápido" é a mesma opinião com menos precisão. Cite ou corte.

Nunca delete uma instrução operacional por falta de fonte. Marcar é melhor que deletar: uma instrução marcada pode ser verificada por alguém que sabe, uma deletada desapareceu.

Para um documento cujas afirmações são principalmente externas, execute cite-or-refuse para a obtenção de fontes e fact-check-document para uma auditoria completa de afirmações antes de continuar.

Passagem 3 — conciso

Um fato, um lugar. Para cada fato, escolha a única seção onde um leitor procurando por ele chegará primeiro. Declare-o ali, por completo. Em qualquer outro lugar, ou delete a repetição ou substitua por um ponteiro nomeando exatamente aquela seção.

Delete completamente:

• Aberturas de preenchimento: "Vale notar que", "Simplesmente", "Basicamente", "Como você pode ver".
• Instruções para fazer o que o leitor já está fazendo: "Para instalar, execute o comando de instalação".
• Títulos de seção repetidos como primeiras frases.
• Ressenvas defensivas que não mudam nenhuma ação.
• Exemplos que demonstram a mesma coisa que um exemplo anterior.

Comprima:

• Mais de três itens comparados em mais de dois atributos → uma tabela.
• Um parágrafo que lista coisas paralelas → uma lista.
• Uma frase cujo sujeito é uma nominalização → o verbo ("fazer uma determinação" → "decidir").

O piso de compressão. Pare quando remover a próxima palavra remover um fato. Um documento mais curto que perdeu um fato é uma regressão, não uma vitória. Contagem de palavras é um sintoma do trabalho, nunca seu alvo.

A única duplicação condicionalmente sancionada é a repetição inicial e final do bloco crítico para o alvo agente, passando do limite de comprimento definido na Passagem 4. Abaixo desse limite é uma repetição como qualquer outra, e vai embora.

Passagem 4 — organize para o leitor declarado

Compartilhado: a lei de ordenação

Ordene pelo que bloqueia o leitor, não pela história do assunto:

1. O que é isso — uma frase, sem preâmbulo.
2. Pré-requisitos que bloqueiam todo o resto — a variável de ambiente sem a qual nada começa, a credencial, a versão necessária.
3. Operações destrutivas e irreversíveis — qualquer coisa que delete, sobrescreva, gaste dinheiro ou não possa ser desfeita. Isso é colocação por consequência, não por tópico: vai perto do topo mesmo quando o comando é obscuro, e é marcado, não meramente mencionado.
4. O caminho principal — a coisa que a maioria dos leitores veio fazer, do começo ao fim.
5. Todo o resto, do mais usado primeiro.
6. Casos de borda, solução de problemas e tabelas de referência por último.

Um bloco de resumo pertence ao topo quando o documento tem mais de cerca de cinco seções; ele lista os fatos que um leitor precisa antes de poder fazer qualquer coisa, não um resumo da prosa.

--target=agent

O leitor é um modelo que carrega o documento como contexto, muitas vezes após grep por um termo e ler apenas a fatia correspondente. Produza um documento com esta forma:

1. Um bloco crítico primeiro, sempre; o mesmo bloco na íntegra por último apenas além de ~100 linhas. Pré-requisitos, operações destrutivas e restrições rígidas vão primeiro, independentemente do comprimento. A degradação perdida-no-meio (Liu et al., TACL 2024) é medida em contextos multi-documento na faixa de milhares a dezenas de milhares de tokens — um documento curto o suficiente para ser lido em uma passagem não tem "meio" nesse sentido, e uma cópia no final é pura duplicação sem benefício de recuperação. Duplique apenas quando o documento passar do mesmo limite de ~100 linhas que lhe rende uma lista de conteúdos (#9 abaixo), onde um leitor de grep-e-fatia pode plausivelmente cair no meio do documento e perder o bloco. Abaixo do limite, declare uma vez, no topo, e pare — uma segunda cópia ali é uma regressão que a passagem 3 deveria ter pego, não uma característica deste alvo. Quando for justificado: intitule a primeira cópia ## Restrições críticas e a última ## Restrições críticas (repetição) — duas âncoras únicas, um corpo idêntico, o único par de cabeçalhos quase duplicados que o documento pode conter.
2. Fraseado positivo. Declare a ação a ser tomada. Onde uma proibição for genuinamente necessária, coloque a alternativa positiva na mesma frase: "escreva em state/, não em /tmp". Modelos lidam com afirmações negadas mensuravelmente pior do que com as afirmativas.
3. Um cabeçalho, uma unidade recuperável. Todo cabeçalho é único dentro do documento, literal e feito das palavras que um agente procuraria — exceto pelo par de bloco crítico acima. Sua seção é autônoma: nenhum "como descrito acima", nenhum pronome cujo referente está em outra seção.
4. Identificadores literais no ponto de uso. Caminhos completos, linhas de comando exatas, nomes exatos de variáveis de ambiente, nomes exatos de arquivos — toda vez, não uma vez com referências posteriores.
5. Afirmações verificáveis em vez de narrativa. Um comando, um caminho, um valor, uma condição de saída. Se uma frase não pode ser verificada, é provavelmente justificativa — mantenha apenas onde muda o que o agente faz.
6. Apenas estrutura Markdown — cabeçalhos, listas, código em bloco, tabelas pequenas. Não adicione um esquema de marcação XML a um documento Markdown; reserve blocos JSON ou YAML para conteúdo que é genuinamente dados de máquina para leitura.
7. Forma mais curta que mantém cada fato. O comprimento da entrada degrada a recuperação por si só, e conteúdo topicamente adjacente que não responde nada atua como distrator — prosa quase correta é pior que ausência.
8. Sem contradições. Duas afirmações que discordam são piores que nenhuma. Resolva-as antes de escrever.
9. Uma lista de conteúdos apenas a partir de ~100 linhas, já que o agente pode ler uma fatia em vez do arquivo inteiro e de outra forma não consegue ver o escopo.

Aceitação: um agente que faz grep de um cabeçalho e lê apenas aquela seção age corretamente.

--target=human

O leitor escaneia antes de ler e lê uma minoria das palavras. Onde a formatação não oferece pistas, esse escaneamento degenera em uma varredura em forma de F pela borda esquerda — a estrutura é o que impede isso, não o que imita. Produza um documento com esta forma:

1. O ponto na primeira frase do documento e de cada seção. Conteúdo mais importante nos primeiros dois parágrafos; um leitor que para ali tem o que veio buscar.
2. Linhas com carga frontal. Todo cabeçalho, marcador e parágrafo começa com suas palavras carregadas de informação — as primeiras duas palavras de uma linha são lidas, o resto é escaneado.
3. Cabeçalhos descritivos: "Configure o diretório de estado", nunca "Visão Geral", "Notas", "Detalhes" ou "Seção 3".
4. Uma ideia por parágrafo, aproximadamente quatro frases no máximo.
5. Linguagem objetiva. Redação neutra supera mensuravelmente a redação promocional para usabilidade; este é um resultado de compreensão, não uma preferência de estilo.
6. Tabelas para comparação, prosa para raciocínio. Mais de três itens em mais de dois atributos → tabela. Explicação conectada, causal ou matizada permanece em prosa — fragmentar um argumento em marcadores perde as ligações.
7. Vocabulário do domínio permanece. Defina um termo uma vez, inline, no primeiro uso. Não simplifique a precisão técnica, e não reescreva em direção a uma pontuação de fórmula de legibilidade — essas pontuações não veem organização e penalizam terminologia correta.
8. Uma lista de conteúdos a partir de cerca de duas telas ou cinco seções.

Aceitação: um leitor pode completar a tarefa que o documento descreve usando apenas o documento.

O que deve diferir entre os alvos

Decisão	--target=human	--target=agent
Restrições críticas	uma vez, na primeira tela, marcadas	uma vez no topo sob ~100 linhas; primeiro e repetidas na íntegra por último além disso
Independência das seções	seções podem construir sobre anteriores	toda seção é autônoma
Referências cruzadas	"veja acima" é aceitável	nomeie o cabeçalho exato
Cabeçalhos	descritivos e legíveis	únicos, literais, moldados para grep
Proibições	"não faça X" é aceitável	"faça Y" carrega a proibição
Identificadores	introduza uma vez, depois abreve	completos e literais toda vez
Raciocínio	a prosa mantém os laços causais	mantenha apenas onde muda uma ação
Lista de conteúdos	a partir de ~2 telas	a partir de ~100 linhas
Comprimento	cerca de metade das palavras originais	forma mais curta mantendo cada fato

Verificação de divergência — OBRIGATÓRIA. Antes de escrever o arquivo, nomeie pelo menos três decisões que esta execução tomou de forma diferente por causa do alvo declarado e coloque-as no relatório. Fe

… [truncado para tradução]