Communitygithub.com

Desnarrar

Elimina comentarios meta-narrativos — texto que describe el artefacto en el que reside, reafirma lo que el lector ya ve o narra el proceso que lo produjo — de textos de interfaz, documentación, comentarios de código, mensajes de commit y descripciones de PR.

¿Qué es Desnarrar?

Desnarrar es una habilidad diseñada para eliminar meta-comentarios redundantes en artefactos de desarrollo, como UI copy, documentación, comentarios de código, mensajes de commit y descripciones de pull requests. Se enfoca en eliminar texto que narra el artefacto en sí mismo (p. ej., "Esta sección describe...", tooltips que repiten etiquetas, comentarios que reafirman la siguiente línea de código) porque agentes de IA generan este tipo de contenido constantemente al incorporar su cadena de pensamiento en cada superficie que tocan. La habilidad complementa a `unslop` (que corrige el estilo de la prosa generada por IA) eliminando texto que es superfluo por definición. Se aplica mediante una "prueba de eliminación": si al quitar mentalmente el texto el lector no pierde nada, o si el texto podría aparecer sin cambios en otro proyecto o PR, debe eliminarse. La habilidad cubre superficies específicas: UI copy, documentación y READMEs, comentarios de código, y commits/PRs. También incluye excepciones claras: narración en vivo (como un mensaje de instalación mientras se ejecuta), comentarios que explican el "por qué" (racional, invariantes, advertencias), instrucciones que la interfaz no puede mostrar (formatos, restricciones, efectos secundarios), y TODO con enlace de seguimiento. Es útil para cualquier desarrollador que revise o genere contenido escrito, especialmente al trabajar con asistentes de IA que tienden a sobrenarrar.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/T0mSIlver/skills/tree/HEAD/unnarrate

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Desnarrar?

Complemento de unslop. unslop corrige cómo suena la prosa de IA; esto elimina texto que no debería existir en absoluto: meta-comentarios — escritura que narra el artefacto a su propia audiencia. Una barra de progreso ya anuncia el progreso; "el progreso se muestra mientras se ejecuta" a su lado es un segundo signo redundante. Los agentes producen esto constantemente porque narran su cadena de pensamiento en cada superficie que tocan.

La prueba de eliminación

Elimina cualquier oración, etiqueta o comentario cuyo único contenido sea:

  1. una descripción del artefacto en el que vive ("Esta sección describe..."),
  2. algo que el lector ya puede ver (un tooltip que repite la etiqueta, un comentario que repite la siguiente línea), o
  3. el proceso que lo produjo (// Según lo solicitado, extraído en un helper).

Dos comprobaciones deciden casos difíciles:

  • Elimínalo mentalmente. Si el lector no pierde nada, era un no-op — texto que parece hacer algo pero no cambia nada.
  • Portabilidad. Si la línea podría aparecer sin cambios en otro proyecto, otro PR, o sobre código diferente, no dice nada sobre este. Córtala.

Qué cortar, por superficie

Texto de UI

  • Texto que describe un comportamiento que la interfaz ya realiza: "El progreso se muestra mientras se instala", "Aparece un spinner mientras se carga", "La lista se actualiza automáticamente". El widget es el significante; no agregues uno verbal.
  • Texto "Cargando..." al lado de un spinner visible; "Archivo subido exitosamente" → "Archivo subido".
  • Tooltips y texto de ayuda que repiten la etiqueta: campo "Ciudad de nacimiento", ayuda "Ingrese la ciudad de su nacimiento".
  • Narración posicional: "Haga clic en el botón a continuación para enviar", "Seleccione una opción del menú desplegable".
  • Texto de onboarding/marcas de guía que enumera cada control en lugar de señalar la única acción no obvia.
  • Duplicados de accesibilidad: aria-label="Botón de envío" en un <button>, alt="Imagen de un gráfico" (los lectores de pantalla ya anuncian el rol).

Documentación y READMEs

  • "Este documento describe...", "En esta guía, haremos...", "Bienvenido a la documentación de X". Empieza con el contenido.
  • Secciones de descripción general que solo anuncian las secciones que siguen; párrafos finales "En resumen" que repiten la página.
  • Docstrings que repiten la firma (get_user(id) — "Obtiene el usuario por id"); <summary>Obtiene o establece X</summary>. PEP 257 prohíbe exactamente esto.
  • "El siguiente ejemplo muestra cómo..." encima de un ejemplo; prosa que repite el bloque de código adyacente.
  • Viñetas de características e introducciones de sección que serían ciertas para cualquier proyecto.

Comentarios de código

  • Repetir la siguiente línea: // Importar React, // Devolver el valor, // Iterar sobre elementos.
  • Banners de sección: // ===== HELPER =====, // --- Paso 3: Validar ---.
  • Narración de plan y fases: // Fase 2: refactorizar, // Usando el modelo Foo recién creado.
  • Narración de registro de cambios: // Cambiado de useState a useReducer, // Eliminado el manejador anterior. El historial de Git contiene esto.
  • Comentarios dirigidos al revisor en lugar del lector futuro: // Nota: mantuve este comportamiento intacto.

Commits y PRs

  • Listas con viñetas que repiten el diff archivo por archivo; "Este PR añade..." seguido del título textual.
  • Secciones de plantilla llenas de repetición; "Plan de prueba: ejecutó las pruebas" sin detalles.
  • Narración de esfuerzo: "Refactorización exhaustiva", "Compatibilidad hacia atrás preservada cuidadosamente". Declara hechos que un revisor pueda verificar.

Conservar — no todo lo que narra es un no-op

  • La narración en vivo es un significante; la narración estática es la señal. Un agente que transmite "Instalando dependencias…" mientras trabaja es retroalimentación real. El texto que describe que esa retroalimentación existe es el antipatrón.
  • Los comentarios de "por qué" se quedan: justificación, invariantes, advertencias sobre comportamiento no obvio, enlaces a problemas e incidentes. La regla elimina la repetición, no los comentarios — iguala la densidad de comentarios del código circundante.
  • Las instrucciones que portan información que la superficie no puede mostrar se quedan: formatos ("AAAA-MM-DD"), restricciones ("8+ caracteres"), efectos secundarios ("esto envía un correo al equipo"), advertencias de irreversibilidad.
  • El texto alternativo real se queda. Elimina el prefijo "Imagen de...", conserva la descripción de lo que muestra la imagen.
  • Los TODO con un enlace de seguimiento se quedan; un // TODO: mejorar esto sin enlace se va.

Aplicarlo

  1. Revisa las superficies modificadas en busca de los patrones anteriores. Elimina, no reescribas — la mayoría de los aciertos no necesitan reemplazo.
  2. Cuando la eliminación deje un vacío real, arregla el artefacto (etiqueta más clara, control autoexplicativo), no la narración.
  3. Luego ejecuta unslop en lo que sobrevive.

reference/terminology.md nombra el fenómeno por comunidad (metadiscurso, happy talk, comentarios obvios, no-ops) con fuentes, para citar o extender la lista de verificación.

Skills relacionados