@saulwade/swl-ses 2.3.0 → 2.4.1

package/habilidades/legacy-code-rescue/SKILL.md

@@ -1,267 +1,268 @@
----
-name: legacy-code-rescue
-description: >
-  Técnicas para trabajar con código heredado sin tests, siguiendo la metodología
-  de Michael Feathers ("Working Effectively with Legacy Code"). Cubre
-  identificación de seams, characterization tests para capturar comportamiento
-  real (no el deseado), patrones para introducir cambios sin romper
-  (sprout method, sprout class, wrap method, wrap class), técnicas para romper
-  dependencias problemáticas, y orden de prioridad cuando se hereda código
-  sin cobertura. Cargar cuando se herede código sin tests, cuando un módulo
-  crítico tenga cobertura <30%, o cuando se planee refactoring de un sistema
-  heredado.
-version: "1.0.0"
-evolved: false
-herramientasPermitidas: [Read]
-exclusiones:
-  - "No cargar para refactoring de código moderno con buena cobertura — si los tests existen y cubren el área a refactorear, basta con `tdd-workflow`. Este skill es específico para código sin red de seguridad."
-  - "No cargar para migración entre versiones de framework — usar `deprecacion-migracion`. Este skill cubre rescate de código heredado en general, no actualizaciones de stack."
-  - "No cargar para deprecación planificada de features — usar `deprecacion-migracion`. Este skill cubre el problema inverso: código que NO se quiere deprecar pero hay que cambiar con seguridad."
-  - "No cargar para optimización de rendimiento de código moderno — los patrones aquí (especialmente characterization tests) priorizan seguridad sobre velocidad. Si la prioridad es perf, usar `performance-baseline` y profilers."
-evolvable: true
----
-
-# Legacy Code Rescue
-
-Adaptado de "Working Effectively with Legacy Code" (Michael Feathers, 2004).
-Definición operativa de Feathers: **legacy code es código sin tests**, sin
-importar su edad o calidad aparente.
-
-## Cuándo cargar
-
-- Se hereda un módulo crítico con cobertura <30% y hay que cambiarlo.
-- Se diagnostica un bug en código que nadie ha tocado en meses/años.
-- Se planea un refactor de un sistema sin red de seguridad de tests.
-- Se necesita agregar una feature en código que actualmente no se puede
-  testear de forma aislada.
-- Se reciben quejas tipo "tengo miedo de tocar X porque puede romper Y".
-
-## Cuándo NO cargar
-
-- El código tiene cobertura ≥80% y los tests pasan — usar `tdd-workflow`.
-- Se está migrando entre versiones de framework — usar `deprecacion-migracion`.
-- Se está deprecando una feature intencionalmente — usar `deprecacion-migracion`.
-- El objetivo es optimizar rendimiento — los patrones aquí priorizan seguridad
-  sobre velocidad; usar `performance-baseline` y profilers.
-
-## Directiva primaria
-
-**Antes de cambiar código heredado, capturar lo que hace**, no lo que se
-supone que debe hacer. El comportamiento actual (incluidos sus bugs) es
-la fuente de verdad — algún caller probablemente depende de cada peculiaridad.
-
-Orden estricto:
-1. **Caracterizar** el comportamiento actual con tests.
-2. **Romper dependencias** lo mínimo necesario para que los tests sean posibles.
-3. **Cambiar** el código.
-4. **Refactorizar** ya con red de seguridad.
-
-NO empezar refactorizando "porque el código está feo". Sin tests, cada cambio
-es una apuesta.
-
----
-
-## Identificar seams (costuras)
-
-Un **seam** es un punto donde el comportamiento del programa puede cambiarse
-sin editar el código original. Los seams son la palanca para introducir
-tests sin romper nada.
-
-### Tipos de seams
-
-| Tipo | Cuándo aplica | Cómo se activa |
-|------|---------------|----------------|
-| **Object seam** | OOP con polimorfismo | Inyectar una subclase/mock que herede |
-| **Preprocessing seam** | C/C++ con `#define` | Macros o preprocesador |
-| **Link seam** | Lenguajes compilados con linker | Sustituir librería en build |
-| **Method seam** (Python/JS) | Lenguajes dinámicos | Monkeypatching, importlib |
-
-En Python/TypeScript modernos, el object seam es el predominante:
-inyectar dependencias en lugar de instanciarlas dentro del constructor.
-
-### Identificar seams en código existente
-
-Buscar:
-- `new SomeClass()` dentro de constructores → object seam latente al refactorizar.
-- Llamadas estáticas a clases globales → buscar wrappers o usar dependency injection.
-- Imports de módulos con efectos secundarios → candidato a method seam.
-- Funciones puras escondidas dentro de métodos largos → extraer es seam barato.
-
----
-
-## Characterization tests — capturar el comportamiento real
-
-Un **characterization test** documenta lo que el código HACE, no lo que
-debería hacer. Son la red de seguridad mínima antes de cualquier cambio.
-
-### Receta
-
-1. Tomar el código y ejecutarlo con un input concreto.
-2. Capturar el output exacto (incluido errores, side effects, state final).
-3. Escribir un test que assert ese output específico.
-4. Repetir con varios inputs representativos: caso típico, edge cases
-   conocidos, inputs malformados, valores extremos.
-5. Cuando el test pasa, **es la verdad** — incluso si revela un bug.
-
-```python
-# Ejemplo: función legacy sin tests
-def calcular_descuento(precio, tipo_cliente):
-    # ... 80 líneas de if/else, redondeos extraños, edge cases ocultos
-    return total
-
-# Characterization test — captura el comportamiento ACTUAL
-def test_caracterizacion_descuento():
-    # Input típico
-    assert calcular_descuento(100, "VIP") == 85.0
-    # Edge case observado: tipo_cliente vacío
-    assert calcular_descuento(100, "") == 100.0
-    # Bug aparente, pero callers pueden depender de él
-    assert calcular_descuento(0, "VIP") == 0.0
-    # Negativos: el código devuelve negativos sin validar — documentarlo
-    assert calcular_descuento(-50, "VIP") == -42.5
-```
-
-### Reglas para characterization tests
-
-- **No "arreglar" bugs** mientras se caracteriza — eso viene después.
-- Si el comportamiento parece incorrecto, escribir un test que lo
-  documente Y abrir un ticket separado para discutir el cambio.
-- Apuntar a cubrir los flujos que se van a tocar — no toda la base de
-  código.
-- Tests rápidos > tests perfectos. Un test feo que corre es mejor que
-  uno elegante que no se escribió.
-
----
-
-## Patrones para cambio seguro
-
-Cuando hay que agregar comportamiento sin tocar código existente.
-
-### Sprout Method
-
-Si necesitas lógica nueva dentro de un método legacy difícil de testear,
-**escribe la lógica nueva como método aparte** (con tests propios) y
-llámalo desde el método legacy.
-
-```python
-# Antes — quieres agregar validación al método legacy
-def procesar_orden(orden):
-    # 200 líneas legacy intocables
-    ...
-
-# Después — la nueva validación vive aparte y SÍ es testeable
-def procesar_orden(orden):
-    # 200 líneas legacy intocables
-    if not _validar_disponibilidad_inventario(orden):  # nuevo
-        return ResultadoOrden.fallo("sin stock")
-    ...
-
-def _validar_disponibilidad_inventario(orden):
-    """Nuevo método con tests propios (no toca el legacy)."""
-    return all(item.cantidad <= item.producto.stock for item in orden.items)
-```
-
-### Sprout Class
-
-Cuando la lógica nueva es suficientemente grande, va en una **clase nueva**
-en lugar de un método. Misma idea: lógica nueva con tests, llamada desde
-el legacy.
-
-### Wrap Method
-
-Si necesitas ejecutar algo ANTES o DESPUÉS de un método legacy, renombra
-el original a algo interno (`_procesar_orden_original`) y crea uno nuevo
-con la firma original que llame al wrap + el original.
-
-```python
-def procesar_orden(orden):  # firma pública intacta
-    _registrar_intento(orden)         # nueva pre-acción, testeable
-    resultado = _procesar_orden_original(orden)
-    _registrar_resultado(resultado)   # nueva post-acción, testeable
-    return resultado
-
-def _procesar_orden_original(orden):
-    # 200 líneas legacy intocables, ahora son privadas
-    ...
-```
-
-### Wrap Class
-
-Para wrap de un sistema más grande: una clase nueva con la misma interfaz
-delega al legacy y agrega comportamiento alrededor (decorator pattern).
-
----
-
-## Romper dependencias
-
-Algunos legacy methods son intratables por dependencias:
-- Conexiones a BD/red en el constructor.
-- Singletons globales que se acceden en cualquier parte.
-- Llamadas a `time.now()`, `random()`, filesystem.
-
-Técnicas (en orden de invasividad creciente):
-
-1. **Subclass and Override Method**: hereda de la clase legacy, sobreescribe
-   el método problemático con un mock para los tests.
-2. **Extract Interface / Extract Class**: extrae una interfaz pequeña con
-   solo los métodos que el código usa, e inyecta una implementación de prueba.
-3. **Parameterize Method/Constructor**: inyecta como parámetro lo que antes
-   se obtenía globalmente (clock, random, IO).
-4. **Replace Function with Function Pointer / Strategy**: cambiar funciones
-   estáticas por callables inyectables.
-
-Aplicar la técnica MENOS invasiva que resuelva el problema. Cuanto más
-invasiva, más riesgo de romper algo durante el rescate.
-
----
-
-## Anti-patrones
-
-- **Refactorizar antes de tener characterization tests**: cualquier cambio
-  estructural sin red de seguridad es una apuesta.
-- **"Mejorar" el comportamiento mientras se caracteriza**: si parece un
-  bug, documéntalo en un ticket y déjalo intacto en el characterization
-  test. Cambios funcionales van en commits separados con su propia revisión.
-- **Apuntar a 100% de cobertura del módulo entero**: el objetivo es
-  cubrir lo que se va a tocar. Cobertura completa puede tomar meses;
-  cubrir el slice de cambio toma horas.
-- **Borrar código "muerto" sin verificar**: en legacy, algo que parece
-  muerto puede ser invocado por reflection o cron. Buscar referencias
-  con `grep -r` antes de borrar.
-- **Sustituir "todo" con un mock**: si el test pasa solo porque mockeaste
-  todas las dependencias, ya no testea nada. Mockear solo lo necesario
-  para aislar el código bajo prueba.
-
----
-
-## Gotchas / Errores comunes no obvios
-
-- **Characterization test "perfecto" que se rompe en CI por orden no determinista**: el código legacy depende del orden de iteración de un dict (Python <3.7) o del timezone del servidor. Causa: comportamiento dependiente de entorno. Solución: capturar la dependencia (forzar timezone UTC en el test, ordenar collections antes de assert) y documentar la dependencia ambiental como bug a discutir.
-- **Sprout Method que sí toca el legacy "solo un poquito"**: el desarrollador agrega un `if condicion_nueva` dentro del legacy en lugar de extraer. Causa: parece más simple. Solución: si tocas el legacy, ya no es sprout; o caracterizas primero, o aplicas wrap method que NO modifica el cuerpo original.
-- **Inyectar dependencia con un default que llama al global**: `def __init__(self, db=None): self.db = db or get_global_db()`. Causa: querer mantener compatibilidad con callers viejos. Solución: el default escondido invalida la inyección — los tests acaban tocando el global. Aceptar que romper la firma es parte del rescate; agregar wrappers de compatibilidad fuera de la clase si es necesario.
-- **Cobertura como métrica engañosa**: 80% de cobertura de líneas pero los asserts solo verifican que "no lanza excepción". Causa: tests escritos para subir el número, no para capturar comportamiento. Solución: cada characterization test debe tener al menos un assert sobre el output o side effect concreto, no solo `assert resultado is not None`.
-- **Mock de la BD que devuelve datos perfectos donde el legacy maneja datos sucios**: el código legacy tiene defensas contra datos inconsistentes que el mock no reproduce. Causa: el mock idealiza la realidad. Solución: el mock debe reproducir la sucidad observada en producción (NULLs inesperados, encodings raros, duplicados) — caracterizar la entrada real es parte del rescate.
-
-## Orden de prioridad cuando se hereda código
-
-1. **Estabilizar**: identificar el módulo más crítico, escribir
-   characterization tests sobre los flujos que se van a tocar pronto.
-2. **Aislar**: romper dependencias problemáticas con seams para que el
-   módulo crítico pueda testearse en isolation.
-3. **Cubrir**: agregar tests sobre código nuevo (Sprout/Wrap) y sobre
-   regresiones detectadas.
-4. **Cambiar**: hacer el cambio funcional pedido, ya con red de seguridad.
-5. **Refactorizar**: mejorar la estructura ya que está cubierta. NO antes.
-
-NO refactorices código que no piensas tocar. La cobertura no es un fin
-en sí mismo — es palanca para cambios futuros.
-
-## Checklist antes de tocar código heredado
-
-- [ ] ¿Existen characterization tests sobre la zona de cambio?
-- [ ] Si no: ¿se escribieron antes de cualquier modificación?
-- [ ] ¿Las dependencias bloqueantes (DB, red, time, random) están aisladas?
-- [ ] ¿El cambio funcional va en un commit separado del refactor estructural?
-- [ ] ¿Se documentaron en tickets los bugs detectados durante la caracterización?
-- [ ] ¿La cobertura nueva es del slice tocado, no del módulo completo?
-- [ ] ¿El sprout/wrap se queda fuera del cuerpo legacy original?
+---
+name: legacy-code-rescue
+description: >
+  Técnicas para trabajar con código heredado sin tests, siguiendo la metodología
+  de Michael Feathers ("Working Effectively with Legacy Code"). Cubre
+  identificación de seams, characterization tests para capturar comportamiento
+  real (no el deseado), patrones para introducir cambios sin romper
+  (sprout method, sprout class, wrap method, wrap class), técnicas para romper
+  dependencias problemáticas, y orden de prioridad cuando se hereda código
+  sin cobertura. Cargar cuando se herede código sin tests, cuando un módulo
+  crítico tenga cobertura <30%, o cuando se planee refactoring de un sistema
+  heredado.
+version: "1.0.1"
+evolved: false
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para refactoring de código moderno con buena cobertura — si los tests existen y cubren el área a refactorear, basta con `tdd-workflow`. Este skill es específico para código sin red de seguridad."
+  - "No cargar para migración entre versiones de framework — usar `deprecacion-migracion`. Este skill cubre rescate de código heredado en general, no actualizaciones de stack."
+  - "No cargar para deprecación planificada de features — usar `deprecacion-migracion`. Este skill cubre el problema inverso: código que NO se quiere deprecar pero hay que cambiar con seguridad."
+  - "No cargar para optimización de rendimiento de código moderno — los patrones aquí (especialmente characterization tests) priorizan seguridad sobre velocidad. Si la prioridad es perf, usar `performance-baseline` y profilers."
+evolvable: true
+---
+
+# Legacy Code Rescue
+
+Adaptado de "Working Effectively with Legacy Code" (Michael Feathers, 2004).
+Definición operativa de Feathers: **legacy code es código sin tests**, sin
+importar su edad o calidad aparente.
+
+## Cuándo cargar
+
+- Se hereda un módulo crítico con cobertura <30% y hay que cambiarlo.
+- Se diagnostica un bug en código que nadie ha tocado en meses/años.
+- Se planea un refactor de un sistema sin red de seguridad de tests.
+- Se necesita agregar una feature en código que actualmente no se puede
+  testear de forma aislada.
+- Se reciben quejas tipo "tengo miedo de tocar X porque puede romper Y".
+
+## Cuándo NO cargar
+
+- El código tiene cobertura ≥80% y los tests pasan — usar `tdd-workflow`.
+- Se está migrando entre versiones de framework — usar `deprecacion-migracion`.
+- Se está deprecando una feature intencionalmente — usar `deprecacion-migracion`.
+- El objetivo es optimizar rendimiento — los patrones aquí priorizan seguridad
+  sobre velocidad; usar `performance-baseline` y profilers.
+
+## Directiva primaria
+
+**Antes de cambiar código heredado, capturar lo que hace**, no lo que se
+supone que debe hacer. El comportamiento actual (incluidos sus bugs) es
+la fuente de verdad — algún caller probablemente depende de cada peculiaridad.
+
+Orden estricto:
+1. **Caracterizar** el comportamiento actual con tests.
+2. **Romper dependencias** lo mínimo necesario para que los tests sean posibles.
+3. **Cambiar** el código.
+4. **Refactorizar** ya con red de seguridad.
+
+NO empezar refactorizando "porque el código está feo". Sin tests, cada cambio
+es una apuesta.
+
+---
+
+## Identificar seams (costuras)
+
+Un **seam** es un punto donde el comportamiento del programa puede cambiarse
+sin editar el código original. Los seams son la palanca para introducir
+tests sin romper nada.
+
+### Tipos de seams
+
+| Tipo | Cuándo aplica | Cómo se activa |
+|------|---------------|----------------|
+| **Object seam** | OOP con polimorfismo | Inyectar una subclase/mock que herede |
+| **Preprocessing seam** | C/C++ con `#define` | Macros o preprocesador |
+| **Link seam** | Lenguajes compilados con linker | Sustituir librería en build |
+| **Method seam** (Python/JS) | Lenguajes dinámicos | Monkeypatching, importlib |
+
+En Python/TypeScript modernos, el object seam es el predominante:
+inyectar dependencias en lugar de instanciarlas dentro del constructor.
+
+### Identificar seams en código existente
+
+Buscar:
+- `new SomeClass()` dentro de constructores → object seam latente al refactorizar.
+- Llamadas estáticas a clases globales → buscar wrappers o usar dependency injection.
+- Imports de módulos con efectos secundarios → candidato a method seam.
+- Funciones puras escondidas dentro de métodos largos → extraer es seam barato.
+
+---
+
+## Characterization tests — capturar el comportamiento real
+
+Un **characterization test** documenta lo que el código HACE, no lo que
+debería hacer. Son la red de seguridad mínima antes de cualquier cambio.
+
+### Receta
+
+1. Tomar el código y ejecutarlo con un input concreto.
+2. Capturar el output exacto (incluido errores, side effects, state final).
+3. Escribir un test que assert ese output específico.
+4. Repetir con varios inputs representativos: caso típico, edge cases
+   conocidos, inputs malformados, valores extremos.
+5. Cuando el test pasa, **es la verdad** — incluso si revela un bug.
+
+```python
+# Ejemplo: función legacy sin tests
+def calcular_descuento(precio, tipo_cliente):
+    # ... 80 líneas de if/else, redondeos extraños, edge cases ocultos
+    return total
+
+# Characterization test — captura el comportamiento ACTUAL
+def test_caracterizacion_descuento():
+    # Input típico
+    assert calcular_descuento(100, "VIP") == 85.0
+    # Edge case observado: tipo_cliente vacío
+    assert calcular_descuento(100, "") == 100.0
+    # Bug aparente, pero callers pueden depender de él
+    assert calcular_descuento(0, "VIP") == 0.0
+    # Negativos: el código devuelve negativos sin validar — documentarlo
+    assert calcular_descuento(-50, "VIP") == -42.5
+```
+
+### Reglas para characterization tests
+
+- **No "arreglar" bugs** mientras se caracteriza — eso viene después.
+- Si el comportamiento parece incorrecto, escribir un test que lo
+  documente Y abrir un ticket separado para discutir el cambio.
+- Apuntar a cubrir los flujos que se van a tocar — no toda la base de
+  código.
+- Tests rápidos > tests perfectos. Un test feo que corre es mejor que
+  uno elegante que no se escribió.
+
+---
+
+## Patrones para cambio seguro
+
+Cuando hay que agregar comportamiento sin tocar código existente.
+
+### Sprout Method
+
+Si necesitas lógica nueva dentro de un método legacy difícil de testear,
+**escribe la lógica nueva como método aparte** (con tests propios) y
+llámalo desde el método legacy.
+
+```python
+# Antes — quieres agregar validación al método legacy
+def procesar_orden(orden):
+    # 200 líneas legacy intocables
+    ...
+
+# Después — la nueva validación vive aparte y SÍ es testeable
+def procesar_orden(orden):
+    # 200 líneas legacy intocables
+    if not _validar_disponibilidad_inventario(orden):  # nuevo
+        return ResultadoOrden.fallo("sin stock")
+    ...
+
+def _validar_disponibilidad_inventario(orden):
+    """Nuevo método con tests propios (no toca el legacy)."""
+    return all(item.cantidad <= item.producto.stock for item in orden.items)
+```
+
+### Sprout Class
+
+Cuando la lógica nueva es suficientemente grande, va en una **clase nueva**
+en lugar de un método. Misma idea: lógica nueva con tests, llamada desde
+el legacy.
+
+### Wrap Method
+
+Si necesitas ejecutar algo ANTES o DESPUÉS de un método legacy, renombra
+el original a algo interno (`_procesar_orden_original`) y crea uno nuevo
+con la firma original que llame al wrap + el original.
+
+```python
+def procesar_orden(orden):  # firma pública intacta
+    _registrar_intento(orden)         # nueva pre-acción, testeable
+    resultado = _procesar_orden_original(orden)
+    _registrar_resultado(resultado)   # nueva post-acción, testeable
+    return resultado
+
+def _procesar_orden_original(orden):
+    # 200 líneas legacy intocables, ahora son privadas
+    ...
+```
+
+### Wrap Class
+
+Para wrap de un sistema más grande: una clase nueva con la misma interfaz
+delega al legacy y agrega comportamiento alrededor (decorator pattern).
+
+---
+
+## Romper dependencias
+
+Algunos legacy methods son intratables por dependencias:
+- Conexiones a BD/red en el constructor.
+- Singletons globales que se acceden en cualquier parte.
+- Llamadas a `time.now()`, `random()`, filesystem.
+
+Técnicas (en orden de invasividad creciente):
+
+1. **Subclass and Override Method**: hereda de la clase legacy, sobreescribe
+   el método problemático con un mock para los tests.
+2. **Extract Interface / Extract Class**: extrae una interfaz pequeña con
+   solo los métodos que el código usa, e inyecta una implementación de prueba.
+3. **Parameterize Method/Constructor**: inyecta como parámetro lo que antes
+   se obtenía globalmente (clock, random, IO).
+4. **Replace Function with Function Pointer / Strategy**: cambiar funciones
+   estáticas por callables inyectables.
+
+Aplicar la técnica MENOS invasiva que resuelva el problema. Cuanto más
+invasiva, más riesgo de romper algo durante el rescate.
+
+---
+
+## Anti-patrones
+
+- **Refactorizar antes de tener characterization tests**: cualquier cambio
+  estructural sin red de seguridad es una apuesta.
+- **"Mejorar" el comportamiento mientras se caracteriza**: si parece un
+  bug, documéntalo en un ticket y déjalo intacto en el characterization
+  test. Cambios funcionales van en commits separados con su propia revisión.
+- **Apuntar a 100% de cobertura del módulo entero**: el objetivo es
+  cubrir lo que se va a tocar. Cobertura completa puede tomar meses;
+  cubrir el slice de cambio toma horas.
+- **Borrar código "muerto" sin verificar**: en legacy, algo que parece
+  muerto puede ser invocado por reflection o cron. Buscar referencias
+  con `grep -r` antes de borrar.
+- **Sustituir "todo" con un mock**: si el test pasa solo porque mockeaste
+  todas las dependencias, ya no testea nada. Mockear solo lo necesario
+  para aislar el código bajo prueba.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Characterization test "perfecto" que se rompe en CI por orden no determinista**: el código legacy depende del orden de iteración de un dict (Python <3.7) o del timezone del servidor. Causa: comportamiento dependiente de entorno. Solución: capturar la dependencia (forzar timezone UTC en el test, ordenar collections antes de assert) y documentar la dependencia ambiental como bug a discutir.
+- **Sprout Method que sí toca el legacy "solo un poquito"**: el desarrollador agrega un `if condicion_nueva` dentro del legacy en lugar de extraer. Causa: parece más simple. Solución: si tocas el legacy, ya no es sprout; o caracterizas primero, o aplicas wrap method que NO modifica el cuerpo original.
+- **Inyectar dependencia con un default que llama al global**: `def __init__(self, db=None): self.db = db or get_global_db()`. Causa: querer mantener compatibilidad con callers viejos. Solución: el default escondido invalida la inyección — los tests acaban tocando el global. Aceptar que romper la firma es parte del rescate; agregar wrappers de compatibilidad fuera de la clase si es necesario.
+- **Cobertura como métrica engañosa**: 80% de cobertura de líneas pero los asserts solo verifican que "no lanza excepción". Causa: tests escritos para subir el número, no para capturar comportamiento. Solución: cada characterization test debe tener al menos un assert sobre el output o side effect concreto, no solo `assert resultado is not None`.
+- **Mock de la BD que devuelve datos perfectos donde el legacy maneja datos sucios**: el código legacy tiene defensas contra datos inconsistentes que el mock no reproduce. Causa: el mock idealiza la realidad. Solución: el mock debe reproducir la sucidad observada en producción (NULLs inesperados, encodings raros, duplicados) — caracterizar la entrada real es parte del rescate.
+- **Codemod por regex sin balanceo de llaves inserta en el bloque estructural equivocado cuando el ancla no es única**: un codemod que inserta tras "el `],` de cierre" asume que esa ancla aparece una sola vez — si el archivo tiene otra (`FormBuilder.group({...})`, arrays anidados), la inserción cae dentro del bloque equivocado y el archivo queda silenciosamente corrupto. Causa: regex no entiende estructura; cuenta patrones, no llaves. Solución: balancear llaves/corchetes desde el ancla (parser mínimo o AST real tipo `ts-morph`/`libcst`) y SIEMPRE cerrar con build completo (`ng build`, `tsc`, `pyflakes`) + auditoría del 100% de las inserciones — el build atrapa la corrupción sintáctica; la auditoría manual, la semántica. Origen: SIGAF 2026-07-02 — 4 de 43 archivos corruptos, detectados solo por `ng build`.
+
+## Orden de prioridad cuando se hereda código
+
+1. **Estabilizar**: identificar el módulo más crítico, escribir
+   characterization tests sobre los flujos que se van a tocar pronto.
+2. **Aislar**: romper dependencias problemáticas con seams para que el
+   módulo crítico pueda testearse en isolation.
+3. **Cubrir**: agregar tests sobre código nuevo (Sprout/Wrap) y sobre
+   regresiones detectadas.
+4. **Cambiar**: hacer el cambio funcional pedido, ya con red de seguridad.
+5. **Refactorizar**: mejorar la estructura ya que está cubierta. NO antes.
+
+NO refactorices código que no piensas tocar. La cobertura no es un fin
+en sí mismo — es palanca para cambios futuros.
+
+## Checklist antes de tocar código heredado
+
+- [ ] ¿Existen characterization tests sobre la zona de cambio?
+- [ ] Si no: ¿se escribieron antes de cualquier modificación?
+- [ ] ¿Las dependencias bloqueantes (DB, red, time, random) están aisladas?
+- [ ] ¿El cambio funcional va en un commit separado del refactor estructural?
+- [ ] ¿Se documentaron en tickets los bugs detectados durante la caracterización?
+- [ ] ¿La cobertura nueva es del slice tocado, no del módulo completo?
+- [ ] ¿El sprout/wrap se queda fuera del cuerpo legacy original?

package/habilidades/meta-skills-estandar/SKILL.md

@@ -9,7 +9,7 @@ description: >
   idiomas de framework y mapeo a frameworks de seguridad. Cargar cuando se
   esté escribiendo o auditando un SKILL.md y se necesiten patrones avanzados
   que no están en la regla core.
-version: "1.1.1"
+version: "1.1.2"
 herramientasPermitidas: [Read, Write, Edit]
 exclusiones:
   - "No cargar si solo se necesita el frontmatter obligatorio, el límite de líneas o la estructura de directorio — eso está en la regla core `reglas/skills-estandar.md` que se carga siempre."