Ephasme/refine-document

Refinar Documento

Toma un documento y produce una versión que un lector sin historial con el proyecto pueda usar: libre de legado, factual, concisa, organizada y moldeada para el lector declarado.

Cuatro pasos, orden fijo, luego una puerta de verificación. Todo lo eliminado se escribe en un archivo de registro, por lo que una decisión incorrecta es recuperable.

Invocación

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

Bandera	Por defecto	Efecto
--target	agent	Para qué lector optimiza el último paso. Cambia el documento, no solo el tono — ver Paso 4.
--no-record	desactivado	Omite el archivo de registro. Las eliminaciones se vuelven irrecuperables excepto desde el control de versiones.

Antes de tocar el archivo:

1. Confirma que la solicitud nombra este documento. Esto reescribe el archivo del usuario en su lugar.
2. Confirma que el archivo está rastreado y limpio en control de versiones. Si no es así, dilo y obtén una autorización explícita — con --no-record esa es la única ruta de recuperación restante.
3. Indica el objetivo con el que estás ejecutando en tu primer mensaje, incluso cuando sea el predeterminado. Un valor predeterminado silencioso hace que un documento se moldee para el lector equivocado.
4. Documentos múltiples: ejecuta este procedimiento una vez por documento, un sub-agente cada uno cuando los sub-agentes estén disponibles, pasando el mismo objetivo y banderas a cada uno. Un sub-agente posee exactamente un archivo.

Salidas

Salida	Ruta	Contenido
Documento refinado	la ruta original, en su lugar	solo estado actual, moldeado para el objetivo
Registro	{nombre}.changelog.md, mismo directorio	todo lo eliminado, textual y ubicado — de solo añadido entre ejecuciones
Informe	tu respuesta	ver Informe

Orden de pasos

Ejecuta los pasos en este orden, como cuatro lecturas separadas del documento. Cada uno reduce la entrada para el siguiente, y fuera de orden se deshacen mutuamente — comprimir prosa que el paso 1 iba a eliminar desperdicia el trabajo, y organizar antes de comprimir organiza relleno.

1. Eliminar legado — elimina todo lo que solo tiene sentido como referencia al pasado.
2. Factual — cada afirmación sobreviviente se verifica, cita o marca.
3. Conciso — un hecho, un lugar, la forma más corta que mantenga el hecho.
4. Organizar — crítico primero, luego la forma del objetivo.

Paso 1 — eliminar legado

SUB-HABILIDAD REQUERIDA: usa strip-legacy-content para este paso. Posee la taxonomía de legado, la regla de eliminar-no-reescribir, y el formato {nombre}.changelog.md que esta herramienta también escribe. Mapa --no-record a su --no-changelog.

Donde esa sub-habilidad no esté disponible, elimina: narrativas de historial y evolución, registros de decisiones y ADRs, avisos de obsolescencia, guías de migración y actualización, registros de cambios y notas de versión incrustados, secciones de retrocompatibilidad, alternativas rechazadas, comentarios fechados, secciones reemplazadas. Elimina los fragmentos; no reescribas la prosa superviviente — los pasos 2-4 lo harán.

La regla de funcionalidad obsoleta. Una funcionalidad marcada como obsoleta no es automáticamente legado. Aplica esta prueba y registra qué rama tomaste:

¿Tiene la funcionalidad un uso que no sea "apoyar el sistema antiguo"?

• No — existe solo para retrocompatibilidad. Elimina la funcionalidad y su aviso.
• Sí — es comportamiento actual. Consérvala, elimina la línea de tiempo de eliminación y el marco "desde v1", y márcala en el registro.

Paso 2 — factual

Cada afirmación que hace el documento es una declaración, incluidas las que heredó. Clasifica cada una y toma la acción correspondiente. No hay quinta opción.

Clase	Señal	Acción
Verificable, artefacto accesible	comportamiento, banderas, valores por defecto, rutas, comandos, claves de configuración, y puedes leer el código, la configuración o el --help	Verifícalo. Verdadero: conserva. Falso: corrígelo.
Verificable, artefacto inaccesible	las mismas afirmaciones, sin repositorio, sin binario y sin documentación para contrastar	Conserva la afirmación exactamente como la establece la fuente, sin marcar, y listala en el informe como no verificada.
Fuente externa posible	estándares, comportamiento de protocolo, comportamiento de productos de terceros, soporte de versiones	Cita la fuente primaria en línea con su fecha o versión. Sin fuente aceptable: elimina la afirmación.
Comparativa o promocional	"10 veces más rápido", "mejor de su clase", "fulgurante", "elegante", "la mayoría de los ingenieros está de acuerdo", y cualquier comparación cuyo otro término no sea parte del sistema actual ("más ligero que Kafka")	Elimínala, a menos que exista una medición citable — entonces indica la medición y su fuente. Conserva el hecho superviviente: "encola trabajos con Redis Streams".
Inverificable y peligrosa	una afirmación no verificada sobre la que un lector podría actuar de forma irreversible: pérdida de datos, gasto, credenciales, un comando destructivo, un límite de seguridad	Consérvala, márcala como [unverified] en el documento, y listala en el informe.

El marcador es para peligros, no para procedencia. Un documento sobre un artefacto al que no puedes acceder es principalmente afirmaciones no verificadas, y marcar cada una enseña al lector a ignorar el marcador. La procedencia no verificada pertenece al informe y al registro; [unverified] en el documento está reservado para las afirmaciones cuyo fallo el lector no puede deshacer. Si más de un puñado de marcadores sobreviven en el documento, has clasificado procedencia como peligro — reclasifica.

Nunca inventes un hecho que el documento fuente no tuviera. Ni una ubicación de configuración, ni un valor por defecto, ni un formato de archivo, ni un requisito previo — ni siquiera uno que sea casi seguro que es cierto. Un hecho inferido expresado de forma plana es indistinguible de uno verificado, y este paso es lo único que se interpone entre el lector y una respuesta incorrecta segura. Si la fuente guarda silencio, el documento refinado guarda silencio.

Nunca suavices una afirmación sin fuente en una más vaga. "Aproximadamente 10 veces más rápido" reescrito como "muy rápido" es la misma opinión con menos precisión. Cítalo o elimínalo.

Nunca elimines una instrucción operativa por falta de fuente. Marcar es mejor que eliminar: una instrucción marcada puede ser verificada por alguien que sepa, una eliminada desaparece.

Para un documento cuyas afirmaciones son en su mayoría externas, ejecuta cite-or-refuse para la obtención de fuentes y fact-check-document para una auditoría completa de afirmaciones antes de continuar.

Paso 3 — conciso

Un hecho, un lugar. Para cada hecho, elige la única sección donde un lector que lo busca llegará primero. Exprésalo allí, completo. En cualquier otro lugar, elimina la repetición o reemplázala con un puntero que nombre esa sección exactamente.

Eliminar directamente:

• Abridores de relleno: "Vale la pena señalar que", "Simplemente", "Básicamente", "Como puedes ver".
• Instrucciones para hacer lo que el lector ya está haciendo: "Para instalar, ejecuta el comando de instalación".
• Títulos de sección repetidos como primeras frases.
• Advertencias defensivas que no cambian ninguna acción.
• Ejemplos que demuestran lo mismo que un ejemplo anterior.

Comprimir:

• Más de tres elementos comparados en más de dos atributos → una tabla.
• Un párrafo que enumera cosas paralelas → una lista.
• Una oración cuyo sujeto es una nominalización → el verbo ("hacer una determinación" → "decidir").

El suelo de compresión. Detente cuando eliminar la siguiente palabra elimina un hecho. Un documento más corto que perdió un hecho es una regresión, no un logro. El recuento de palabras es un síntoma del trabajo, nunca su objetivo.

La única duplicación condicionalmente permitida es la repetición de cabeza y cola del bloque crítico para el objetivo agente, más allá del umbral de longitud establecido en el Paso 4. Por debajo de ese umbral es una repetición como cualquier otra, y desaparece.

Paso 4 — organizar para el lector declarado

Compartido: la ley de ordenación

Ordena por lo que bloquea al lector, no por la historia del tema:

1. Qué es esto — una oración, sin preámbulo.
2. Requisitos previos que bloquean todo lo demás — la variable de entorno sin la cual nada comienza, la credencial, la versión requerida.
3. Operaciones destructivas e irreversibles — cualquier cosa que elimine, sobrescriba, gaste dinero, o no se pueda deshacer. Esto es ubicación por consecuencia, no por tema: va cerca de la parte superior incluso cuando el comando es oscuro, y está marcada, no solo mencionada.
4. La ruta principal — lo que la mayoría de los lectores vinieron a hacer, de principio a fin.
5. Todo lo demás, lo más usado primero.
6. Casos límite, resolución de problemas y tablas de referencia al final.

Un bloque de resumen pertenece a la parte superior cuando el documento tiene más de unas cinco secciones; enumera los hechos que un lector necesita antes de poder hacer algo, no un resumen de la prosa.

--target=agent

El lector es un modelo que carga el documento como contexto, a menudo después de buscar un término y leer solo el fragmento coincidente. Produce un documento con esta forma:

1. Un bloque crítico primero, siempre; el mismo bloque textual al final solo más allá de ~100 líneas. Los requisitos previos, las operaciones destructivas y las restricciones estrictas van primero independientemente de la longitud. La degradación de "perdido en el medio" (Liu et al., TACL 2024) se mide en contextos de múltiples documentos en el rango de miles a decenas de miles de tokens — un documento lo suficientemente corto para leer en una sola pasada no tiene "medio" en ese sentido, y una copia al final es pura duplicación sin beneficio de recuperación. Duplica solo cuando el documento supere el mismo umbral de ~100 líneas que merece una lista de contenidos (#9 a continuación), donde un lector que busca y corta puede plausiblemente aterrizar a mitad del documento y perderse el bloque. Por debajo del umbral, indícalo una vez, al principio, y detente — una segunda copia allí es una regresión que el paso 3 debería haber detectado, no una característica de este objetivo. Cuando esté justificado: encabeza la primera copia ## Restricciones críticas y la última ## Restricciones críticas (repetición) — dos anclas únicas, un cuerpo idéntico, el único encabezado casi duplicado que el documento puede contener.
2. Fraseo positivo. Indica la acción a tomar. Cuando una prohibición sea genuinamente necesaria, pon la alternativa positiva en la misma oración: "escribe en state/, no en /tmp". Los modelos manejan las declaraciones negadas notablemente peor que las afirmativas.
3. Un encabezado, una unidad recuperable. Cada encabezado es único dentro del documento, literal, y compuesto por las palabras que un agente buscaría — aparte del par de bloques críticos anterior. Su sección es independiente: sin "como se describió anteriormente", sin pronombre cuyo referente está en otra sección.
4. Identificadores literales en el punto de uso. Rutas completas, líneas de comando exactas, nombres exactos de variables de entorno, nombres exactos de archivos — cada vez, no una vez con referencias posteriores.
5. Declaraciones verificables sobre narrativa. Un comando, una ruta, un valor, una condición de salida. Si una oración no se puede verificar, probablemente sea justificación — consérvala solo donde cambie lo que hace el agente.
6. Solo estructura Markdown — encabezados, listas, código delimitado, tablas pequeñas. No agregues un esquema de etiquetado XML a un documento Markdown; reserva bloques JSON o YAML para contenido que sea genuinamente datos legibles por máquina.
7. La forma más corta que conserve cada hecho. La longitud de entrada degrada la recuperación por sí sola, y el contenido temáticamente adyacente que no responde a nada actúa como distractor — la prosa casi correcta es peor que la ausencia.
8. Sin contradicciones. Dos declaraciones que no concuerdan son peores que ninguna. Resuélvelas antes de escribir.
9. Una lista de contenidos solo más allá de ~100 líneas, ya que el agente puede leer un fragmento en lugar del archivo completo y, de otro modo, no puede ver el alcance.

Aceptación: un agente que busque un encabezado y lea solo esa sección actúa correctamente.

--target=human

El lector escanea antes de leer y lee una minoría de las palabras. Cuando el formato no ofrece señales, ese escaneo se degrada en un barrido en forma de F por el borde izquierdo — la estructura es lo que lo previene, no lo que lo imita. Produce un documento con esta forma:

1. El punto en la primera oración del documento y de cada sección. El contenido más importante en los primeros dos párrafos; un lector que se detiene allí tiene lo que vino a buscar.
2. Líneas con carga frontal. Cada encabezado, viñeta y párrafo comienza con sus palabras portadoras de información — las primeras dos palabras de una línea se leen, el resto se escanea.
3. Encabezados descriptivos: "Configurar el directorio de estado", nunca "Resumen", "Notas", "Detalles" o "Sección 3".
4. Una idea por párrafo, aproximadamente cuatro oraciones como máximo.
5. Lenguaje objetivo. La redacción neutral supera notablemente a la redacción promocional en usabilidad; esto es un resultado de comprensión, no una preferencia de estilo.
6. Tablas para comparación, prosa para razonamiento. Más de tres elementos en más de dos atributos → tabla. La explicación conectada, causal o matizada permanece en prosa — fragmentar un argumento en viñetas pierde los enlaces.
7. El vocabulario del dominio se conserva. Define un término una vez, en línea, en el primer uso. No simplifiques la precisión técnica, y no reescribas hacia una puntuación de fórmula de legibilidad — esas puntuaciones no pueden ver la organización y penalizan la terminología correcta.
8. Una lista de contenidos más allá de aproximadamente dos pantallas o cinco secciones.

Aceptación: un lector puede completar la tarea que el documento describe usando solo el documento.

Qué debe diferir entre objetivos

Decisión	--target=human	--target=agent
Restricciones críticas	una vez, en la primera pantalla, marcado	una vez arriba bajo ~100 líneas; primero y repetido textual al final más allá
Independencia de secciones	las secciones pueden basarse en anteriores	cada sección autocontenida
Referencias cruzadas	"ver arriba" está bien	nombra el encabezado exacto
Encabezados	descriptivos y legibles	únicos, literales, con forma de búsqueda
Prohibiciones	"no hagas X" está bien	"haz Y" lleva la prohibición
Identificadores	introducir una vez, luego acortar	completos y literales cada vez
Razonamiento	la prosa conserva los enlaces causales	conserva solo donde cambia una acción
Lista de contenidos	más allá de ~2 pantallas	más allá de ~100 líneas
Longitud	aproximadamente la mitad de las palabras originales	la forma más corta que conserve cada hecho

Verificación de divergencia — REQUERIDO. Antes de escribir el archivo, nombra al menos tres decisiones que esta ejecución haya tomado de manera diferente debido al objetivo declarado, y colócalas en el informe.

Informe

Después de escribir el archivo y el registro, reporta:

Elemento	Contenido
Ruta	el archivo modificado
Lector	agent o human
Cambio neto	líneas añadidas/eliminadas/marcadas en el documento
Divergencias	la lista del paso 4 — qué decisiones fueron moldeadas por el objetivo
No verificado	afirmaciones que este paso archivó como no verificadas con un artefacto inaccesible, en su categoría
Marcado pel.	afirmaciones que este paso marcó como [unverified] por riesgo de acción irreversible
Citas añadidas	fuentes añadidas en línea en el paso 2, con su fecha o versión
Inferencias rechazadas	hechos que este paso consideró inferir de la fuente y no infirió — "el archivo de configuración por defecto es app.yml"
Eliminaciones del paso 1 que son recuperables del registro	depende del nivel de detalle que elijas

Marcas de límite de contexto

Esta sección es borrada por la pasada de organización final. La sub-habilidad strip-legacy-content escribe en su lugar el contenido que necesita de aquí. Antes de que se ejecute la pasada de organización, el texto que sigue puede ser movido a la sub-habilidad por refine-document internamente. Pero una vez que comienza la pasada de organización, cualquier contenido debajo de esta línea es eliminado.

Marcas de límite de contexto

Esta sección es borrada por la pasada de organización final. La sub-habilidad strip-legacy-content escribe en su lugar el contenido que necesita de aquí. Antes de que se ejecute la pasada de organización, el texto que sigue puede ser movido a la sub-habilidad por refine-document internamente. Pero una vez que comienza la pasada de organización, cualquier contenido debajo de esta línea es eliminado.