reducing-entropy

Visión general de la skill reducing-entropy

La skill reducing-entropy es una ayuda de refactorización de uso exclusivamente manual pensada para reducir un codebase de forma deliberada. No es un prompt genérico de limpieza ni debería activarse automáticamente. Úsala cuando el objetivo real sea tener menos piezas en movimiento, menos código total y una inclinación mucho más fuerte por borrar de la que tendría una refactorización normal.

Para quién encaja mejor esta skill

reducing-entropy encaja mejor para quienes están:

• refactorizando código maduro que no deja de crecer
• revisando planes de “cleanup” que en realidad pueden introducir más abstracciones
• decidiendo si una feature, una capa o un helper debería existir en absoluto
• intentando simplificar la arquitectura, no solo reordenarla

Resulta especialmente relevante en reducing-entropy for Refactoring, donde el instinto equivocado suele ser introducir estructura nueva en vez de eliminar la que ya existe.

El trabajo real que resuelve

Esta skill ayuda a responder una pregunta más difícil que “¿qué cambio debería hacer?”. Plantea:

• cómo debería quedar el codebase después del cambio
• si el estado final realmente es más pequeño
• qué se puede borrar en vez de conservar

Por eso es más útil que un prompt genérico de “simplifica este código” cuando buscas un sesgo claro hacia una reducción neta.

Qué hace diferente a reducing-entropy

Su principal diferencia está en la métrica de éxito: la cantidad final de código, no el esfuerzo de implementación.

Eso significa que favorecerá resultados como:

• escribir una migración pequeña que elimine un subsistema grande
• sustituir tipos personalizados por estructuras de datos más simples
• borrar comportamientos opcionales en vez de generalizarlos
• descartar diseños “más limpios” si aumentan el código total

Restricción importante antes de adoptarla

No es una opción segura por defecto para cualquier tarea. El repositorio deja claro que reducing-entropy es solo de uso manual y está pensada para ejecutarse con una intención explícita del usuario. Si tu equipo prioriza la extensibilidad, la preparación para el futuro o la estabilidad de interfaces por encima de reducir código en una tarea concreta, esta skill puede empujar demasiado hacia el borrado.

Qué leer antes de decidir si usarla

Lee primero estos archivos:

• skills/reducing-entropy/SKILL.md
• skills/reducing-entropy/README.md
• skills/reducing-entropy/references/simplicity-vs-easy.md

Después, revisa uno o dos mindsets de referencia adicionales según tu situación:

• references/data-over-abstractions.md
• references/design-is-taking-apart.md
• references/expensive-to-add-later.md

Esas referencias importan porque la skill espera que tomes decisiones apoyándote al menos en un enfoque concreto de simplificación antes de actuar.

Cómo usar la skill reducing-entropy

Instalación y configuración de reducing-entropy

Si usas el patrón Skills CLI de este repositorio, instala la skill con:

npx skills add softaworks/agent-toolkit --skill reducing-entropy

Después abre la carpeta de la skill instalada y lee SKILL.md antes del primer uso. No es una skill de automatización lista para usar; es un marco de decisión que conviene invocar de forma deliberada.

Empieza con el mindset de referencia obligatorio

Un detalle práctico que muchos pasan por alto: reducing-entropy te indica que cargues al menos un archivo de references/ antes de continuar. Hazlo primero y deja claro cuál estás usando.

Buenas combinaciones:

• usa simplicity-vs-easy.md cuando un patrón conocido resulte tentador, pero pesado
• usa data-over-abstractions.md cuando el código esté lleno de wrappers, managers o tipos personalizados
• usa design-is-taking-apart.md cuando las responsabilidades estén enredadas
• usa expensive-to-add-later.md cuando borrar algo pueda chocar con el coste de reintroducirlo en el futuro

Este paso mejora la calidad del resultado porque le da al modelo una lente concreta de simplificación, en vez de una meta difusa de “dejarlo más limpio”.

Qué información necesita reducing-entropy

Para obtener algo útil, aporta más que un enlace al repo o un volcado de archivos. La skill funciona mejor cuando le das:

• el objetivo aprobado por el usuario
• el comportamiento actual que debe mantenerse
• la parte del codebase que entra en alcance
• restricciones sobre API, migraciones o plazos
• si se permite borrar entre archivos, módulos o features

Ejemplo de input sólido:

“Use reducing-entropy on our billing retry flow. Goal: preserve current retry behavior for Stripe failures, but reduce total code in services/billing/ and workers/retry/. You may remove dead configuration paths and duplicate helper layers. Do not change public API responses or database schema this week.”

Eso es muchísimo mejor que:

“Refactor billing to be simpler.”

Cómo convertir un objetivo difuso en un buen prompt de reducing-entropy

Un buen prompt de reducing-entropy usage suele tener cinco partes:

1. activación explícita
2. alcance objetivo
3. comportamiento protegido
4. permiso de borrado
5. formato de salida

Ejemplo:

“Apply the reducing-entropy skill. Load one reference mindset first and tell me which one you chose. Analyze src/cache/ and src/session/ for the smallest codebase that still supports current login/session behavior. Prefer deletion over reorganization. Reject options that increase total code even if they look cleaner. Give me:

• the smallest end-state design
• what to delete
• what to merge
• risks
• rough before/after code footprint”

Flujo de trabajo recomendado para una refactorización real

Un flujo fiable es:

1. leer SKILL.md
2. elegir un mindset de referencia
3. inspeccionar los límites actuales entre módulos
4. listar el comportamiento que debe sobrevivir
5. plantear las tres preguntas centrales de la skill
6. producir 2–3 estados finales candidatos
7. compararlos por reducción neta de código
8. implementar el resultado viable más pequeño
9. revisar si quedan abstracciones sobrantes y rutas muertas

Esto evita un fallo muy común: ponerse a editar antes de decidir cuál es el diseño mínimo que debería sobrevivir.

Las tres preguntas de reducing-entropy que conviene forzar en cada ejecución

El repositorio estructura la skill alrededor de tres comprobaciones. En la práctica, conviene hacerlas explícitas en el prompt:

• What is the smallest codebase that solves this?
• Does the change result in less total code?
• What can we delete?

Si no fuerzas estas preguntas, el resultado suele volver a caer en consejos típicos de refactorización.

Dónde funciona mejor reducing-entropy

Las tareas donde mejor encaja incluyen:

• colapsar módulos duplicados en una sola ruta más simple
• eliminar wrappers, factories, managers y abstracciones delgadas
• sustituir estructuras personalizadas por datos sencillos más funciones
• borrar features poco usadas o configurabilidad innecesaria
• simplificar un subsistema enredado antes de añadir trabajo nuevo

Por eso reducing-entropy for Refactoring es uno de los mejores encajes: va más de rediseñar el estado final que de pulir el estilo local del código.

Cuándo no usar reducing-entropy

Evita esta skill cuando el trabajo principal sea:

• añadir una capacidad nueva con requisitos futuros inciertos
• mantener una superficie estable de extensión para terceros
• diseñar preocupaciones fundacionales que luego sean costosas de adaptar
• hacer el código más legible sin permiso para borrar o fusionar comportamiento

En esos casos, el sesgo hacia el borrado puede dejar de ser una ventaja y convertirse en un desajuste.

Archivos prácticos del repositorio para leer primero

Para entenderla rápido, sigue este orden de lectura:

1. SKILL.md
2. README.md
3. references/simplicity-vs-easy.md
4. references/design-is-taking-apart.md
5. references/data-over-abstractions.md

Lee adding-reference-mindsets.md solo si quieres entender cómo piensan los autores sobre los archivos filosóficos de apoyo.

Consejos que mejoran de verdad la calidad del resultado

Hay tres tácticas que marcan más diferencia:

• Pide primero la arquitectura mínima del estado final antes de pedir cambios de código.
• Exige borrados explícitos, no solo simplificaciones.
• Haz que el modelo estime qué desaparece: archivos, funciones, clases, ramas, configs.

Eso convierte la skill en un ejercicio real de reducción, no en un simple empujón de estilo.

Preguntas frecuentes sobre la skill reducing-entropy

¿Es reducing-entropy mejor que un prompt normal de refactorización?

Normalmente sí, cuando tu objetivo es una simplificación neta. Un prompt genérico suele proponer capas más limpias, mejores nombres o abstracciones más reutilizables. reducing-entropy funciona mejor cuando esos movimientos harían crecer el codebase y quieres que el modelo se resista a ellos.

¿Reducing-entropy es adecuada para principiantes?

Sí, siempre que la persona principiante ya entienda el sistema actual lo bastante bien como para definir el comportamiento protegido y el alcance. El marco de la skill es simple, pero los buenos resultados dependen de saber qué se puede eliminar sin riesgo.

¿Reducing-entropy significa solo borrar código?

No. Puede justificar escribir algo de código si eso permite borrar mucho más en conjunto. La prueba clave es el estado final. Las adiciones pequeñas son aceptables si sustituyen estructuras mayores.

¿Puedo usar reducing-entropy en trabajo greenfield?

Por lo general, no como guía principal. Es más fuerte para podar o simplificar un codebase existente que para diseñar uno nuevo desde cero.

¿Cómo se compara reducing-entropy con un cleanup normal?

Un cleanup normal suele optimizar la legibilidad local o la organización. La reducing-entropy skill optimiza para tener menos conceptos, menos estructuras y menos código total. Esos objetivos se solapan, pero no son lo mismo.

¿Cuáles son los principales riesgos antes de instalarla?

Los riesgos más importantes son:

• borrar flexibilidad que en realidad sí necesitas
• simplificar en exceso de cara a requisitos futuros
• medir el recuento de líneas de forma demasiado mecánica
• eliminar estructura que existe por motivos operativos reales

Por eso importa el archivo de referencia expensive-to-add-later.md. Aporta una excepción razonada al sesgo puro de borrado.

¿Reducing-entropy encaja en cualquier repositorio?

No. Encaja mejor cuando el crecimiento del código es el problema. Resulta menos adecuada en sistemas muy regulados, plataformas públicas o entornos muy extensibles donde la estructura explícita puede formar parte del propio requisito de producto.

Cómo mejorar la skill reducing-entropy

Dale a reducing-entropy límites más claros

La forma más rápida de mejorar reducing-entropy usage es definir qué no debe cambiar. Sin eso, el modelo puede proponer borrar comportamiento valioso.

Algunos límites útiles:

• “Preserve API shape.”
• “No schema changes.”
• “Keep test coverage expectations.”
• “User-visible behavior must stay identical.”

Los límites claros permiten que la skill sea agresiva sin dejar de ser segura.

Pide comparaciones de estado final, no una sola respuesta

En lugar de pedir una única recomendación, pide dos o tres estados finales candidatos clasificados por:

• reducción total de código
• coste de migración
• riesgo de romper comportamiento
• carga de mantenimiento

Esto hace visibles los tradeoffs y te ayuda a descartar un diseño “mínimo” que hoy sería demasiado arriesgado.

Aporta señales del codebase que revelen entropía

La skill mejora cuando señalas indicios de hinchazón, como:

• lógica duplicada entre módulos
• clases wrapper con comportamiento mínimo
• ramas de configuración para modos sin uso
• capas helper que solo reenvían llamadas
• tipos personalizados allí donde bastarían datos simples

Estas pistas ayudan al modelo a apuntar a oportunidades reales de simplificación en vez de limitarse a hacer retoques cosméticos.

Vigila los modos de fallo más comunes

Los malos resultados más habituales son:

• reorganizar el código en más archivos
• añadir abstracciones para “prepararse para crecer”
• conservar rutas muertas de compatibilidad
• proponer nombres más limpios sin reducir la estructura
• tratar “menos churn” como si fuera el objetivo

Si ves esto, vuelve a dejar clara la métrica central: menos código total en el codebase final.

Usa los archivos de referencia de forma estratégica

Los resultados mejoran cuando eliges el mindset adecuado para el problema:

• usa data-over-abstractions.md para cuestionar diseños cargados de clases
• usa design-is-taking-apart.md para separar responsabilidades mezcladas
• usa simplicity-vs-easy.md cuando la solución conocida esté demasiado acoplada
• usa expensive-to-add-later.md para defender lo poco que realmente merece conservarse

Esta es una de las partes más potentes del repositorio y merece usarse de forma explícita, no pasiva.

Pide candidatos a borrado por categoría

Un patrón de prompt de alto rendimiento es:

“List deletion candidates by category: feature, abstraction, config, compatibility path, helper, type, and file.”

Esa estructura empuja al modelo a mirar más allá de ediciones locales y encontrar oportunidades de reducción más amplias.

Itera después del primer resultado

Tras la primera pasada, haz preguntas de seguimiento como:

• “What remains that exists only to support the old design?”
• “Which abstractions are now redundant?”
• “What can be merged further without changing behavior?”
• “What would you remove if you had to cut this module by 30%?”

Estas preguntas de segunda ronda suelen destapar las ganancias reales.

Valida con complejidad neta, no solo con recuento de líneas

El recuento de líneas importa aquí, pero no lo uses a ciegas. Las mejores mejoras también reducen:

• los conceptos que hay que aprender
• los saltos entre módulos para seguir el comportamiento
• los casos especiales
• las rutas de bifurcación
• la superficie de dependencias

Un codebase más pequeño pero todavía enredado es solo una victoria parcial. El mejor uso de la reducing-entropy guide combina borrado con desacoplamiento.