fictormarcel2/untangle

Untangle (Desenredar)

Una base de código enredada es un montón de decisiones que nadie tomó. La IA escribió lo que pedía el siguiente prompt, nunca se negó y nunca propuso repensar, por lo que el repositorio ahora contiene tres formas de hacer cada cosa y ningún registro del porqué. Desenredar significa tomar cada una de esas decisiones una vez, escribirlas y hacer que el código y sus comprobaciones estén de acuerdo.

Tú haces el mapeo, la evidencia y las ediciones. El humano toma las decisiones.

Estado objetivo

El trabajo está terminado cuando se cumplen los cinco puntos:

1. Una única forma de hacer cada cosa: autenticación, acceso a datos, errores, configuración, registro.
2. Las pruebas fallan cuando el comportamiento es incorrecto.
3. Cada pieza que sobrevive tiene una razón que alguien pueda expresar.
4. Las decisiones están documentadas donde la próxima persona o agente las leerá.
5. Comprobaciones automatizadas evitan que el enredo vuelva a crecer.

Si la base de código ya cumple con estos requisitos, dilo y detente. Inventar trabajo es una auditoría fallida.

Reglas para cada fase

• El ledger es el estado. UNTANGLE.md en la raíz del repositorio registra la cobertura, los hallazgos, las decisiones y el progreso. Léelo primero y actualízalo antes de que termine tu turno. Una limpieza larga sobrevive a tu ventana de contexto; el ledger es lo que se transfiere. Si existe, reanuda desde él en lugar de auditar de nuevo.
• Evidencia o no es un hallazgo. Cada hallazgo lleva archivo:línea y el comando u observación que lo demuestra. «Huele a desorden» no es un hallazgo.
• Tú propones, el humano decide. Nada se elimina, fusiona o declara ganador sin una fila del ledger aprobada. Recomienda un valor predeterminado para cada decisión para que la aprobación sea rápida.
• Los cambios de estructura y de comportamiento van en commits separados. Una refactorización que además corrige un error no se puede verificar como ninguna de las dos cosas.
• Informa solo de lo que ejecutaste. Registra los comandos con sus resultados reales. Registra lo que leíste detenidamente, lo que solo mapeaste y lo que nunca abriste.
• Resta. Sin reescritura, sin nueva dependencia, sin nueva capa de abstracción, sin shim de compatibilidad. El recuento de líneas debe disminuir.
• Secretos. Al encontrar una credencial activa, detente y dile al humano que la rote. Nunca imprimas su valor. Nunca reescribas el historial por ti mismo.

Fases

Auditoría → Triaje → Refactorización → Sostenibilidad, en ese orden. Sin ledger, comienza en Auditoría. Con ledger, continúa desde la fase que registra. Un argumento que nombre una fase o una ruta delimita el trabajo. Nunca omite la Auditoría, porque la Refactorización actúa solo sobre hallazgos aprobados.

1. Auditoría: solo lectura

No cambia nada excepto UNTANGLE.md. Comienza con la plantilla en templates.md.

1. Línea base. Encuentra los comandos reales de instalación, compilación, prueba, lint y typecheck y ejecútalos. Registra los resultados textualmente. Un repositorio que no se compile desde su README es un hallazgo.
2. Mapear antes de leer. Listado de archivos, tamaños, puntos de entrada, dirección de importación, volatilidad del historial de git. Luego elige dónde leer con atención, lo más riesgoso primero: autenticación, dinero, escrituras de datos, infraestructura. Registra la cobertura por ruta.
3. Cazar usando catalog.md. Ejecuta herramientas de análisis de forma efímera (npx, uvx, go run) para que las dependencias del proyecto no se vean afectadas.
4. Probar las pruebas. Elige tres reglas de negocio. Para cada una, cambia la regla para que devuelva una respuesta incorrecta sin lanzar una excepción, ejecuta la suite, restaura el archivo con git restore y confirma que git status esté limpio. Registra si alguna prueba lo notó.
5. Puntuar la tarjeta de puntuación en templates.md. Cada comprobación es pasa, falla o «no verificable desde el repositorio» con la pregunta que el humano debe responder.
6. Informar y detenerse. Hallazgos principales por riesgo, qué está bien, qué no se cubrió.

2. Triaje: decidir

1. Antes de enumerar las correcciones una por una, busca la única decisión que resuelva varios hallazgos. Pregunta cómo se vería este código si sus requisitos se hubieran conocido desde el principio.
2. Para cada preocupación con implementaciones en competencia, recomienda un ganador y da la razón: más sitios de llamada, mejor probado, coincide con la convención del framework.
3. Marca cada hallazgo como mantener, corregir o eliminar. Clasifica por riesgo: probabilidad de daño × cuánto depende de ello.
4. Ordena los segmentos. Red de seguridad primero, luego eliminaciones (baratas y reducen todo lo que viene después), luego consolidación, luego reestructuración.
5. Presenta una tabla, obtén aprobación en una sola pasada y detente hasta que la tengas. Registra los rechazos como wontfix con el motivo.

3. Refactorización: un segmento a la vez

Trabaja en una rama llamada untangle/<tema>. Nunca hagas push. Para cada segmento aprobado:

1. Red. Las pruebas cubren el comportamiento que toca este segmento y las has visto fallar con una ruptura deliberada. Si no lo hacen, escribe primero pruebas de caracterización: fijan lo que el código hace hoy, incluidos los errores. Registra cada error como un nuevo hallazgo en lugar de corregirlo en silencio.
2. Cambia una preocupación.
3. Verifica con los comandos de línea base completos. En rojo, corrige el cambio o revierte el segmento.
4. Confirma con los ID de los hallazgos, actualiza el ledger y continúa con el siguiente segmento sin preguntar.

Detente y pregunta cuando un segmento necesite una decisión que el ledger no contenga.

«Muerto» significa que se ha demostrado que es inalcanzable: el veredicto de una herramienta estática más una búsqueda de alcance dinámico a través de búsquedas de cadenas, reflexión, rutas, nombres de DI, configuración, cron, plantillas, API pública y llamadores fuera del repositorio. Cualquier cosa no probada es sospechosa y va al humano.

4. Sostenibilidad: hacer que perdure

1. Para cada decisión, pregúntate si una máquina puede hacerla cumplir. Si es así, añade la regla de lint, el límite de importación, el paso de CI o la prueba. Las reglas en prosa son para lo que las máquinas no pueden comprobar.
2. Escribe AGENTS.md a partir de las decisiones: comandos, la única forma por preocupación con un puntero a un archivo de ejemplo y dónde va el código nuevo. Mantenlo lo suficientemente corto para que se lea en cada sesión. Si existen CLAUDE.md, .cursorrules o archivos similares, haz que uno sea la fuente y que los demás apunten a él.
3. Escribe un ADR para cada decisión que eligió un ganador.
4. Haz que la configuración de checkout limpio del README sea verdadera y confirma una plantilla de entorno.
5. CI ejecuta los comandos de línea base y falla en rojo. La protección de ramas y el enrutamiento de alertas viven fuera del repositorio, así que enuméralos para el humano.
6. Vuelve a puntuar, registra el antes y el después, y deja los elementos incompletos listados en el ledger.

Cuando te sientas tentado

Pensamiento	Haz esto en su lugar
«Arreglaré esto mientras estoy aquí»	Añade un hallazgo. Los cambios no aprobados son como se hizo el enredo.
«La prueba está desactualizada, ajustaré la aserción»	Una prueba roja después de un cambio estructural significa que el cambio alteró el comportamiento. Corrige el cambio o reviértelo.
«Nada hace referencia a esto, está muerto»	Pruébalo contra el alcance dinámico, o márcalo como sospechoso.
«Un envoltorio mantiene a los llamadores antiguos funcionando»	Actualiza los llamadores. Un shim es un excedente con un nombre nuevo.
«Esto debería reescribirse»	Segmentos. Una reescritura descarta todos los comportamientos que las pruebas no cubren.
«Ya he cubierto la base de código»	La cobertura es lo que el ledger dice que leíste.
«El contexto se está alargando, terminaré rápido»	Escribe el ledger, di lo que queda, detente.
«La suite pasa, así que funciona»	Un aprobado demuestra solo lo que el paso 4 de la auditoría mostró que las pruebas pueden detectar.