escritura-tecnica

name

escritura-tecnica

description

Escribe o mejora prosa técnica que se lee y se acepta — ADRs, READMEs, PR bodies, devlogs, guías, explicaciones y secciones de docs. Aplica los checklists mecánicos destilados de los playbooks de razonamiento de devground (narrativa/voz, síntesis, enseñanza) para que el documento haga su trabajo en vez de ser un muro de texto. Úsala SIEMPRE que vayas a redactar o reescribir un documento técnico — "escribe un ADR", "redacta el README", "mejora este PR body", "documenta esta decisión", "explica cómo funciona X", "escribe la guía de Y", "resume esto", "destila esta discusión", "write an ADR/README/PR", "document this", "explain X", "make this doc clearer", "tighten this up". NO la uses para código, tests, o respuestas conversacionales — solo cuando el entregable es un documento.

Escritura técnica — checklists accionables

Destilado de docs/reasoning-craft-playbook.md (§A narrativa, §B síntesis) y docs/reasoning-craft-playbook-vol2.md (§B enseñanza). Estos checklists son la versión operativa; el detalle, los ejemplos antes/después y la honestidad adversarial viven en esos playbooks.

Paso 0 — Nombra el trabajo del documento (antes de la primera línea)

Un documento tiene un trabajo, no un tema. Escribe qué hará el lector distinto después de leerlo; eso fija la estructura:

Documento	Trabajo	Test de éxito
ADR	persuadir una decisión y sobrevivir la relectura en 2 años	el lector acepta sin leer el Contexto entero
README	que el lector decida en 30s si esto le sirve	título + 1ª frase bastan para filtrar
PR body	justificar el cambio ante un revisor con poco tiempo	el revisor aprueba sin la ronda "¿consideraste X?"
Guía / explicación	que el lector PUEDA hacerlo solo	predice un caso nuevo que no le mostraste

Segunda pregunta obligatoria: ¿qué objeción tendrá el lector, y dónde la respondo? Respóndela antes de que la formule. Un documento sin objeción anticipada es un monólogo.

Estructura por tipo (compacta)

• ADR: herida primero (el daño observado con evidencia, no generalidades) → antipatrón con código real → decisión imperativa y verificable con patrón copiable → consecuencias negativas reales → alternativas con razón de descarte en una frase (incluida "no hacer nada").
• README: qué es + cifra ancla en una línea → "para quién" explícito (filtra al lector equivocado) → camino feliz en ≤3 comandos → detalle progresivo en <details>/docs enlazadas.
• PR body: qué cambia y por qué ahora (efecto, no lista de archivos) → problema con evidencia → enfoque + alternativa descartada en una línea → cómo se verificó (comando concreto) → qué NO cubre.
• Guía: "para qué" en una frase → pasos numerados, cada uno con su verificación ("ejecuta X → deberías ver Y") → jerga con puente en el punto de uso → errores probables y su síntoma.

Heurísticas de prosa (con test mecánico)

• Apertura: la primera frase contiene la conclusión o el dato que la fuerza. Test de borrado: si puedes quitar la primera frase sin perder información, quítala. (Prohibido meta-texto: "en este documento…", "aquí tienes".)
• Por qué antes del qué: toda regla lleva su mecanismo causal (la regla sin porqué se rompe en el primer caso raro). Excepción: material de referencia pura (tabla de API, índice).
• Ritmo: frase corta para veredicto/conclusión; larga para mecanismo/matiz. Tras 3 frases de >25 palabras, la siguiente <10. Un párrafo = una idea.
• Cierre: nunca resumas lo ya dicho. Cierra con la acción siguiente o la frontera ("qué NO cubre esto"). La honestidad ("cuándo NO usar esto") compra más credibilidad que cualquier adjetivo.
• Corta siempre: meta-texto; adjetivos sin medición ("robusto", "potente" → la cifra o nada); hedging doble; la reformulación de cortesía.
• Forma según contenido: ítems intercambiables → lista; estructura paralela de ≥3 → tabla; cadena causal → prosa. Voz activa con agente nombrado. Cada ~30 líneas, ≥1 elemento no-párrafo.

Si estás DESTILANDO (resumir sin aplanar)

• Protege lo no-derivable primero: umbrales, excepciones, contraejemplos. El matiz crítico viaja disfrazado de detalle y es lo primero que un resumen aplana.
• Una línea existe solo si cambia una decisión nombrable. Funde por raíz causal (no por sección de origen), ordena por costo del error, máx. ~10 reglas.
• Test de negación (contra la falsa densidad): si negar la frase es absurdo ("la telemetría debe ser confiable"), no informa — reescríbela con un sustantivo verificable (ruta, umbral, comando) o bórrala.
• Test de reconstrucción: plantea 2-3 casos concretos; si la destilación no determina la decisión, cortaste el umbral que decidía.

Si estás ENSEÑANDO (construir capacidad, no persuadir)

• Enseñar ≠ explicar: el éxito es que el lector prediga un caso nuevo que no mostraste, no que diga "quedó claro". Enseña el generador ("busca donde A confía en B"), no la lista de resultados.
• Ejemplo ancla: el PRIMERO define todo. Elígelo central (la mayoría de casos se le parecen, NO el raro/vistoso), completo (mecanismo esencial sin "ignora esto por ahora"), fértil (de él se derivan los vecinos).
• Capas: una idea verificable por capa; la capa 0 no tiene ni un "salvo/excepto". Cada capa siguiente responde una tensión que la anterior dejó viva. La excepción se difiere hasta que omitirla causaría un error de predicción.
• Maldición del conocimiento: todo término tiene puente antes del primer uso; borra "simplemente/obviamente/solo tienes que" (marcan una compresión que a ti te es automática).
• Cierra con un caso NUEVO + su respuesta, no un resumen.

Modos de falla (los que cometen los modelos)

Falla	Antídoto
Muro de texto uniforme	cada ~30 líneas ≥1 elemento no-párrafo
"Aquí tienes" / relleno de apertura	test de borrado
Conclusión enterrada	escríbela primero, construye hacia atrás
Voz pasiva evasiva ("se decidió")	decisor nombrado
Lista donde iba prosa / prosa donde iba tabla	conectores causales → prosa; estructura paralela → tabla
Simetría de plantilla	espacio proporcional al riesgo, no a las secciones

Antes de entregar

Relee solo las primeras frases de cada sección. Si no cuentan la historia completa, reordena antes de pulir. Donde una regla no capture el juicio, dilo en el documento en vez de fingir que lo captura.