Better Doc
Revise documentos usando dois frameworks complementares:
- Estilo Clássico (Pinker) — Clareza, precisão, necessidade
- Brevidade Inteligente (Axios) — Estrutura, escaneabilidade, impacto
Objetivo: Tornar o texto uma janela transparente para o significado. Brevidade é confiança; extensão é medo.
Regra Crítica: Preservar a Substância
Brevidade ≠ Exclusão. Simplifique a expressão, preserve o significado.
Ao revisar documentos existentes (especialmente prompts):
| Faça | Não Faça |
|---|---|
| Torne requisitos verbosos mais diretos | Exclua requisitos que pareçam longos |
| Condense explicações prolixas | Remova contexto que o leitor precisa |
| Substitua termos vagos por específicos | Abandone restrições ou casos de borda |
| Reestruture para clareza | Perder informações ao reestruturar |
Antes de cortar algo, pergunte:
- Isto transmite um requisito, uma restrição ou um contexto?
- Removê-lo mudaria o resultado?
- Posso dizer a mesma coisa com menos palavras em vez de excluir?
Para prompts especificamente:
- Requisitos enterrados em parágrafos → Extraia como marcadores explícitos
- Restrições implícitas → Torne-as explícitas, não presuma que são óbvias
- Contexto verboso → Condense, mas mantenha se afetar o comportamento
- Exemplos → Mantenha se esclarecerem casos de borda, corte se forem redundantes
Abordagem errada: "Este parágrafo é longo, exclua-o." Abordagem correta: "Este parágrafo contém 3 requisitos. Reescreva como 3 marcadores."
Princípios Principais
Estilo Clássico (8 Princípios)
- Linguagem direta — Voz ativa, atores claros
- Apenas conteúdo necessário — Remova o que não melhora o entendimento
- Sem complexidade artificial — A estrutura serve à clareza, não à decoração
- Específico em vez de abstrato — Termos concretos e verificáveis
- Terminologia consistente — Um nome por conceito
- Intenção clara — Objetivo, restrições, formato de saída (para prompts)
- Ordem centrada no leitor — A sequência segue o caminho do entendimento
- Afirmações verificáveis — Fatos e lógica, não impressões
Brevidade Inteligente (4 Componentes)
- Título forte — 6 palavras ou menos, chame a atenção
- Uma conclusão principal — Primeira frase = a ÚNICA coisa a lembrar
- Por que isso importa — Contexto sobre a relevância para o leitor
- Aprofunde-se — Detalhes opcionais, organizados em marcadores
Para explicações detalhadas: references/principles.md
Fluxo de Revisão
Etapa 1: Classificar o Documento
| Tipo | Áreas de Foco |
|---|---|
| E-mail/Atualização | Estrutura de Brevidade Inteligente, escaneabilidade |
| Prompt/Instrução | Clareza de intenção, restrições, formato |
| Documento técnico | Precisão, terminologia, hierarquia |
| Texto geral | Estilo Clássico, fluxo, necessidade |
Etapa 2: Verificar a Estrutura de Brevidade Inteligente
Para e-mails, atualizações, anúncios:
✓ Título: ≤6 palavras fortes?
✓ Primeira frase: UMA conclusão principal?
✓ "Por que isso importa": Relevância para o leitor clara?
✓ Detalhes: Em marcadores, escaneáveis?
✓ Negrito: Termos-chave destacados?
Etapa 3: Verificar o Estilo Clássico
| Princípio | Sinais de Alerta |
|---|---|
| Linguagem direta | Voz passiva, nominalizações, verbos enterrados |
| Conteúdo necessário | Enchimento, repetição, afirmações óbvias |
| Sem complexidade | Superformatado, marcadores aninhados, cabeçalhos desnecessários |
| Específico | "Vários", "aspectos", jargão indefinido |
| Termos consistentes | Mesma coisa, nomes diferentes |
| Intenção clara | Objetivo ausente, restrições vagas |
| Ordem do leitor | Pulando tópicos, conclusão antes do contexto |
| Verificável | "Parece", afirmações não fundamentadas |
Etapa 4: Verificar Problemas no Nível da Palavra
Regras de palavras da Brevidade Inteligente:
- Palavras curtas vencem: 1 sílaba > 2 > 3
- Corte: Advérbios, palavras fracas, palavras de hesitação
- Verbos ativos sempre
| Corte Isto | Mantenha/Substitua Por |
|---|---|
| "A fim de" | "Para" |
| "Devido ao fato de que" | "Porque" |
| "Neste momento" | "Agora" |
| "Utilizar" | "Usar" |
| "Implementar" | "Fazer" / "Construir" |
| "Facilitar" | "Ajudar" / "Permitir" |
Etapa 5: Relatar Achados
## Resumo da Revisão
**Tipo**: [e-mail/prompt/técnico/geral]
**Geral**: [avaliação em uma linha]
## Estrutura (Brevidade Inteligente)
- Título: [✓/✗ + correção]
- Primeira frase: [✓/✗ + correção]
- Por que isso importa: [✓/✗ + correção]
- Escaneabilidade: [✓/✗ + correção]
## Estilo (Clássico)
[Liste violações com local, problema, correção]
## Revisão Sugerida
[Versão melhorada, se solicitado]
Referência Rápida: Formato de Brevidade Inteligente
Para e-mails e atualizações, use esta estrutura:
**[Título de 6 palavras]**
[UMA frase: a principal conclusão]
**Por que isso importa**: [1-2 frases sobre a relevância para o leitor]
**Próximos passos** / **Aprofunde-se** / **Os detalhes**:
• [Marcador 1]
• [Marcador 2]
• [Marcador 3]
**Conclusão**: [Conclusão final opcional]
Verificações Específicas para Prompts
Estrutura alvo:
Objetivo: [Declaração clara e única]
Restrições:
- [Limite 1]
- [O que NÃO fazer]
- [Limites de tamanho/formato]
Formato de Saída: [Estrutura exata]
Ao melhorar prompts existentes:
| Problema Original | Correção (NÃO excluir) |
|---|---|
| Requisito enterrado em prosa | Extrair → marcador explícito |
| Restrição vaga ("tenha cuidado") | Tornar específica ("nunca exceda X") |
| Suposição implícita | Declarar explicitamente |
| Exemplo redundante | Remover apenas se outro exemplo já cobrir |
| Explicação longa de caso de borda | Condensar, manter a regra |
Lista de verificação antes de finalizar:
- Todos os requisitos originais ainda presentes?
- Restrições mais explícitas do que antes?
- Nada perdido na reestruturação?
- Mais curto E mais claro (não apenas mais curto)?
Sinalizar: Objetivo ausente, termos vagos ("bom", "apropriado"), nenhum formato de saída.
Correções Comuns
| Problema | Antes | Depois |
|---|---|---|
| Passiva | "Os dados são processados" | "O sistema processa os dados" |
| Nominalização | "Tomar uma decisão" | "Decidir" |
| Enchimento | "É importante notar" | [excluir] |
| Palavra longa | "Utilizar" | "Usar" |
| Vago | "Vários fatores" | "Custo, tempo, escopo" |
| Título fraco | "Atualização sobre o projeto" | "Projeto entrega na sexta" |
| Lide enterrada | [parágrafo antes do ponto] | [ponto primeiro] |
Habilidades relacionadas
Parte de uma pequena família de habilidades de agente abertas para comunicação confiável e clara:
- reduce-hallucination — auditar agentes LLM; fundamentar, citar, abster-se.
- better-doc — Estilo Clássico + Brevidade Inteligente.
- numbers — tornar números significativos e exibi-los de forma limpa.