Better Doc
Revisa documentos aplicando dos marcos complementarios:
- Estilo Clásico (Pinker) — Claridad, precisión, necesidad
- Brevedad Inteligente (Axios) — Estructura, escaneabilidad, impacto
Objetivo: Convertir el texto en una ventana transparente al significado. La brevedad es confianza; la extensión es miedo.
Regla Crítica: Preservar el Contenido
Brevedad ≠ Eliminación. Simplifica la expresión, conserva el significado.
Al revisar documentos existentes (especialmente prompts):
| Hacer | No Hacer |
|---|---|
| Hacer los requisitos verbosos más directos | Eliminar requisitos que parezcan largos |
| Condensar explicaciones extensas | Quitar contexto que el lector necesita |
| Reemplazar términos vagos por específicos | Eliminar restricciones o casos límite |
| Reestructurar para mayor claridad | Perder información al reestructurar |
Antes de eliminar algo, pregúntate:
- ¿Esto transmite un requisito, restricción o contexto?
- ¿Eliminarlo cambiaría el resultado?
- ¿Puedo decir lo mismo con menos palabras en lugar de borrar?
Para prompts específicamente:
- Requisitos enterrados en párrafos → Extráelos como viñetas explícitas
- Restricciones implícitas → Hazlas explícitas, no asumas que son obvias
- Contexto verboso → Condensa, pero consérvalo si afecta el comportamiento
- Ejemplos → Consérvalos si aclaran casos límite, elimínalos si son redundantes
Enfoque incorrecto: «Este párrafo es largo, elimínalo». Enfoque correcto: «Este párrafo contiene 3 requisitos. Reescríbelos como 3 viñetas».
Principios Fundamentales
Estilo Clásico (8 Principios)
- Lenguaje directo — Voz activa, actores claros
- Solo contenido necesario — Elimina lo que no mejora la comprensión
- Sin complejidad artificial — La estructura sirve a la claridad, no a la decoración
- Específico sobre abstracto — Términos concretos y verificables
- Terminología consistente — Un nombre por concepto
- Intención clara — Objetivo, restricciones, formato de salida (para prompts)
- Orden centrado en el lector — La secuencia sigue la ruta de comprensión
- Afirmaciones verificables — Hechos y lógica, no impresiones
Brevedad Inteligente (4 Componentes)
- Titular contundente — 6 palabras o menos, que capte la atención
- Una conclusión — La primera frase = lo ÚNICO que recordar
- Por qué es importante — Contexto sobre la relevancia para el lector
- Profundizar — Detalles opcionales, organizados en viñetas
Para explicaciones detalladas: references/principles.md
Flujo de Revisión
Paso 1: Clasificar el Documento
| Tipo | Áreas de Enfoque |
|---|---|
| Correo/Actualización | Estructura de Brevedad Inteligente, escaneabilidad |
| Prompt/Instrucción | Claridad de intención, restricciones, formato |
| Documento técnico | Precisión, terminología, jerarquía |
| Texto general | Estilo clásico, flujo, necesidad |
Paso 2: Verificar la Estructura de Brevedad Inteligente
Para correos, actualizaciones, anuncios:
✓ Titular: ¿≤6 palabras contundentes?
✓ Primera frase: ¿UNA conclusión clave?
✓ «Por qué es importante»: ¿Relevancia clara para el lector?
✓ Detalles: ¿En viñetas y escaneables?
✓ Negritas: ¿Términos clave resaltados?
Paso 3: Verificar el Estilo Clásico
| Principio | Señales de Alarma |
|---|---|
| Lenguaje directo | Voz pasiva, nominalizaciones, verbos enterrados |
| Contenido necesario | Relleno, repetición, afirmaciones obvias |
| Sin complejidad | Sobreformateo, viñetas anidadas, encabezados innecesarios |
| Específico | «Varios», «aspectos», jerga no definida |
| Términos consistentes | Misma cosa, nombres diferentes |
| Intención clara | Objetivo faltante, restricciones vagas |
| Orden para el lector | Saltos de tema, conclusión antes del contexto |
| Verificable | «Parece», afirmaciones sin sustento |
Paso 4: Verificar Problemas a Nivel de Palabra
Reglas de palabras de Brevedad Inteligente:
- Las palabras cortas ganan: 1 sílaba > 2 > 3
- Elimina: Adverbios, palabras débiles, palabras de relleno
- Verbos activos siempre
| Elimina Esto | Conserva/Reemplaza Con |
|---|---|
| «Con el fin de» | «Para» |
| «Debido a que» | «Porque» |
| «En este momento» | «Ahora» |
| «Utilizar» | «Usar» |
| «Implementar» | «Hacer» / «Construir» |
| «Facilitar» | «Ayudar» / «Permitir» |
Paso 5: Informar Hallazgos
## Resumen de Revisión
**Tipo**: [correo/prompt/técnico/general]
**General**: [evaluación en una línea]
## Estructura (Brevedad Inteligente)
- Titular: [✓/✗ + corrección]
- Primera frase: [✓/✗ + corrección]
- Por qué es importante: [✓/✗ + corrección]
- Escaneabilidad: [✓/✗ + corrección]
## Estilo (Clásico)
[Enumera infracciones con ubicación, problema, corrección]
## Revisión Sugerida
[Versión mejorada si se solicita]
Referencia Rápida: Formato de Brevedad Inteligente
Para correos y actualizaciones, usa esta estructura:
**[Titular de 6 palabras]**
[UNA frase: la conclusión clave]
**Por qué es importante**: [1-2 frases sobre relevancia para el lector]
**Qué sigue** / **Profundizar** / **Los detalles**:
• [Viñeta 1]
• [Viñeta 2]
• [Viñeta 3]
**En resumen**: [Conclusión final opcional]
Verificaciones Específicas para Prompts
Estructura objetivo:
Objetivo: [Declaración clara y única]
Restricciones:
- [Límite 1]
- [Qué NO hacer]
- [Límites de longitud/formato]
Formato de Salida: [Estructura exacta]
Al mejorar prompts existentes:
| Problema Original | Corrección (NO eliminar) |
|---|---|
| Requisito enterrado en prosa | Extraer → viñeta explícita |
| Restricción vaga («ten cuidado») | Hacer específica («nunca excedas X») |
| Suposición implícita | Afirmar explícitamente |
| Ejemplo redundante | Eliminar solo si otro ejemplo lo cubre |
| Explicación larga de caso límite | Condensar, conservar la regla |
Lista de verificación antes de finalizar:
- ¿Todos los requisitos originales siguen presentes?
- ¿Las restricciones son más explícitas que antes?
- ¿No se perdió nada en la reestructuración?
- ¿Más corto Y más claro (no solo más corto)?
Señal: Objetivo faltante, términos vagos («bueno», «apropiado»), sin formato de salida.
Correcciones Comunes
| Problema | Antes | Después |
|---|---|---|
| Pasiva | «Los datos son procesados» | «El sistema procesa los datos» |
| Nominalización | «Tomar una decisión» | «Decidir» |
| Relleno | «Es importante destacar que» | [eliminar] |
| Palabra larga | «Utilizar» | «Usar» |
| Vago | «Varios factores» | «Costo, tiempo, alcance» |
| Titular débil | «Actualización del proyecto» | «El proyecto se lanza el viernes» |
| Inicio enterrado | [párrafo antes del punto] | [punto primero] |
Habilidades relacionadas
Parte de una pequeña familia de habilidades abiertas para agentes, orientadas a una comunicación clara y confiable:
- reduce-hallucination — auditar agentes LLM; fundamentar, citar, abstenerse.
- better-doc — Estilo Clásico + Brevedad Inteligente.
- numbers — hacer que los números sean significativos y mostrarlos limpiamente.