¿Es fiable la documentación automatizada de repositorios?

La arqueología de un repositorio puede reconstruir una cantidad sorprendente de documentación, pero no puede recuperar la intención por el mero hecho de leer más archivos. Un mapa de módulos, un grafo estático de llamadas, un posible modelo de datos y buena parte del grafo de dependencias de procesos por lotes son resultados respaldados por pruebas. Etiquetas como "cliente", afirmaciones sobre cuándo es seguro volver a ejecutar un proceso y explicaciones sobre el motivo de una rama son hipótesis hasta que otra fuente las confirma.

Ese límite importa porque la documentación generada suele parecer igual de segura a ambos lados. He visto equipos aceptar un diagrama impecable, planificar una reescritura a su alrededor y descubrir tarde que una regla del planificador o un programa seleccionado de forma dinámica contenía el comportamiento importante. La solución no consiste en rechazar la automatización. Consiste en hacer que cada afirmación generada incluya sus pruebas, su método y sus puntos ciegos conocidos.

Un repositorio demuestra estructura, no propósito

La documentación automatizada de un repositorio es fiable cuando informa sobre estructura observable y explica con exactitud cómo la observó. Los archivos, las declaraciones, las importaciones, los destinos de compilación, las referencias SQL, las instrucciones JCL y las claves literales de configuración dejan rastros que se pueden inspeccionar. Una herramienta puede enumerarlos, conectarlos y señalar las líneas que respaldan cada conexión.

El propósito es distinto. Una tabla llamada ACCT_MST podría contener cuentas de clientes, cuentas internas del libro mayor o un estado temporal de conciliación. El nombre sugiere una interpretación, pero no demuestra ninguna. Una rutina llamada VALIDATE puede rechazar una entrada errónea, aplicar una regla de autorización o limitarse a comprobar anchos de campo. Los comentarios ayudan, pero un comentario obsoleto también es contenido del repositorio, no una verdad privilegiada.

En la documentación generada utilizo tres clases de confianza:

• Observado significa que el repositorio contiene una prueba directa, como una importación, un EXEC PGM o una declaración de clave externa.
• Inferido significa que varias observaciones respaldan una conclusión, como agrupar programas en un módulo de facturación porque comparten tablas y puntos de entrada.
• Sin resolver significa que el repositorio no permite decidir la cuestión, aunque una interpretación parezca probable.

Cada nodo y cada arista también deben citar su origen como una ruta más una línea o un intervalo de instrucciones. Sin procedencia, quien revise el documento no puede distinguir el resultado de un analizador de una suposición del modelo. Una frase generada como "INVOICE escribe en AR_LEDGER" solo sirve si el lector puede inspeccionar el INSERT, la llamada al procedimiento almacenado o la escritura de registro que la respalda.

La distinción también evita un error de categoría frecuente: integridad y exactitud son cosas distintas. Un analizador puede encontrar correctamente todas las llamadas directas de los archivos que entiende y pasar por alto las llamadas realizadas mediante configuración. Su resultado es correcto dentro de un ámbito declarado, pero está incompleto para el sistema en ejecución. La documentación debe informar sobre ambas dimensiones, no convertirlas en una vaga puntuación de confianza.

El mapa de módulos necesita varios tipos de aristas

Un mapa de módulos creíble combina la estructura de directorios con pruebas de dependencia y acceso a datos. Tratar las carpetas de primer nivel como módulos solo funciona en repositorios excepcionalmente disciplinados. Los árboles antiguos suelen agrupar archivos por paquete de despliegue, costumbre de un autor, ubicación de copybooks o una migración que se quedó a medias.

Empiece por las unidades declaradas: proyectos, paquetes, bibliotecas, programas, formularios, procedimientos almacenados, procesos por lotes y destinos de compilación. Después recopile aristas tipadas entre ellas. Entre los tipos útiles están imports, calls, includes, compiles_into, reads, writes, submits y generates. Conserve el tipo. Una tabla compartida es una prueba más débil de un límite de módulo que un destino de compilación, y una inclusión textual no equivale a una llamada en tiempo de ejecución.

El primer artefacto debe ser un inventario legible por máquinas, no una imagen. Por ejemplo:

{"unit":"billing/post_invoice.cbl","kind":"cobol_program","declares":["POSTINV"],"includes":["ARREC"],"reads":["CUSTOMER"],"writes":["AR_LEDGER"],"evidence":["billing/post_invoice.cbl:18-146"]}

Genere los diagramas y el texto desde ese inventario. Así se pueden revisar los cambios: cuando un programa se mueve o mejora un analizador, primero cambia el registro de origen y después todas las vistas. El equipo también puede consultar la documentación en lugar de mirar un grafo que ocupa una pared.

La agrupación exige moderación. Los componentes conectados, las declaraciones de paquetes, los prefijos de nombres, los archivos de propietarios y las unidades de despliegue pueden proponer límites. No deben inventarlos en silencio. Si los programas AR* comparten registros y se despliegan juntos, llame al conjunto grupo de facturación inferido y enumere la regla que lo creó. Después una persona puede aceptarlo, dividirlo o cambiarle el nombre.

El texto generado de cada módulo debe responder preguntas prácticas: ¿qué entra en esta unidad? ¿A qué puede llamar? ¿Qué datos posee y cuáles se limita a tocar? ¿Cómo se compila y despliega? ¿Qué otra unidad se rompería si cambia su interfaz? Un rectángulo de colores que no responde a ninguna de esas preguntas es decoración.

Los grafos estáticos son útiles y previsiblemente incompletos

Un grafo estático de llamadas puede capturar de forma fiable las llamadas cuyos destinos se resuelven directamente desde el código fuente. También puede ofrecer aristas inversas, que suelen ser más útiles al planificar cambios: en vez de preguntar a qué llama una función, los ingenieros preguntan quién puede llegar a la función que quieren sustituir.

El manual de GNU cflow establece precisamente esta diferencia entre grafos directos e inversos para C. También ofrece controles sobre el filtrado de símbolos y el preprocesamiento. Esa salvedad importa. Un grafo depende del analizador del lenguaje, la configuración de preprocesamiento, las opciones de compilación y los puntos de entrada elegidos. Ejecutar un analizador sobre todos los archivos con sus valores predeterminados no equivale a analizar el programa que se compila para producción.

El despacho dinámico crea la primera gran laguna. Los punteros a funciones, la reflexión, la inyección de dependencias, el despacho COM, los proxies generados, el CALL dinámico de COBOL y los nombres de programas formados a partir de datos pueden ocultar el destino. Un escáner de código puede registrar el punto de despacho y la expresión usada para elegir un destino, pero debe crear una arista sin resolver en lugar de adivinar uno.

La ejecución externa crea otra laguna. Los comandos de shell, las API de envío de procesos, los disparadores de base de datos, los consumidores de mensajes y los archivos consultados por otro proceso cruzan límites que un grafo específico de un lenguaje rara vez ve. El repositorio puede contener ambos extremos sin contener una arista directa de símbolos entre ellos.

Registre el modo de resolución de cada arista:

• static cuando la sintaxis y la resolución de símbolos identifican el destino.
• configured cuando un manifiesto o ajuste nombra el destino.
• observed cuando una traza de ejecución registra el destino.
• possible cuando el análisis del despacho produce un conjunto limitado.
• unknown cuando existe el punto de llamada pero no se resuelve el destino.

No elimine las aristas desconocidas para que el dibujo quede más limpio. Suelen ser los elementos más útiles del documento porque identifican dónde hacen falta trazas o una conversación con operaciones. Un grafo con todas las llamadas resueltas en un sistema que usa mucha reflexión o configuración suele estar publicitando su ceguera.

El modelo de datos tiene tres versiones rivales

El repositorio puede proporcionar un esquema declarado, un esquema utilizado y un modelo de negocio implícito. Se solapan, pero los equipos tienen problemas cuando la documentación los presenta como una sola cosa.

El esquema declarado procede de DDL, archivos de migración, mapeos ORM, definiciones de registros, copybooks, reglas de validación e instantáneas de metadatos de base de datos guardadas en el árbol. Permite identificar tablas, columnas, tipos, índices, claves declaradas, nulabilidad y restricciones. PostgreSQL documenta information_schema.columns como vista portátil de información sobre columnas y señala que los tipos específicos de PostgreSQL residen finalmente en pg_catalog. Es una advertencia útil: incluso los metadatos de una base tienen una capa portátil y otra específica del proveedor.

El esquema utilizado procede del código. Las cadenas SQL, los generadores de consultas, la entrada y salida de archivos, las clases de acceso a datos, los enlaces de pantalla y las definiciones de informes muestran qué campos lee o escribe cada programa. Esta vista descubre tablas sin claves externas declaradas pero con uniones constantes, y columnas que existen en DDL pero ya no aparecen en el código del repositorio.

El modelo de negocio implícito añade significado: una cuenta pertenece a un cliente, un estado C significa cerrado o un par de fechas de vigencia representa un periodo de póliza. La automatización puede proponer estas relaciones a partir de nombres, uniones, comprobaciones y transformaciones repetidas. No puede elevarlas a hechos sin un glosario, una prueba, la confirmación de un operador o datos observados.

Una extracción útil mantiene visibles las discrepancias:

SELECT table_schema, table_name, column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
ORDER BY table_schema, table_name, ordinal_position;

Compare esa salida con las referencias del repositorio en vez de elegir una como canónica. Si el código selecciona legacy_code pero el esquema capturado no la contiene, puede haber una instantánea obsoleta, SQL condicional o un esquema de producción distinto. Si el DDL declara una clave externa que ningún código sigue, la restricción sigue contando. La discrepancia es un hallazgo, no una molestia que haya que fusionar hasta hacerla desaparecer.

El linaje de campos exige la misma cautela. Las asignaciones directas y las transformaciones con nombre pueden respaldar una arista de linaje. Un procedimiento almacenado llamado mediante una pasarela genérica, una macro de hoja de cálculo o una exportación editada por un operador rompen la cadena. Marque la ruptura. No dibuje una flecha continua a través de pruebas ausentes.

Las dependencias batch viven fuera del JCL

Un repositorio permite deducir buena parte del grafo de procesos por lotes, pero el JCL o los scripts rara vez contienen por sí solos el calendario de producción. Muestran programas, pasos, procedimientos, conjuntos de datos, ramas según códigos de retorno y envíos explícitos de procesos. Los calendarios, las reglas de precedencia, los recursos, las sustituciones y las acciones de recuperación suelen estar en la base de datos del planificador o en la configuración de operaciones.

La documentación de IBM Workload Scheduler describe predecesores y sucesores de procesos, incluidas condiciones basadas en el estado o el código de retorno. Su documentación sobre el repositorio JCL también indica que el planificador conserva una copia del JCL de los procesos que envía en el plan actual. Esos hechos muestran un límite importante: el JCL enviado es un artefacto de ejecución, mientras que el plan actual contiene el estado de la orquestación. Un repositorio Git con un solo lado no puede demostrar todo el grafo de dependencias.

Dentro del repositorio, extraiga al menos cuatro clases de aristas: orden de pasos, ejecución de programas, flujo de datos y condición explícita. Una arista productor-consumidor inferida porque un proceso escribe un conjunto de datos y otro lo lee debe seguir marcada como inferida. Los nombres de los conjuntos pueden ser generacionales, simbólicos, reemplazarse en el envío o compartirse por motivos ajenos al orden.

Represente el resultado de forma que admita fuentes ausentes:

job: CLOSE_AR
steps:
  - exec: EXTRACT_AR
    writes: [AR.CLOSE.GDG(+1)]
  - exec: POST_AR
    when: EXTRACT_AR.RC <= 4
external_predecessors:
  - name: LOAD_RATES
    source: scheduler_export
unresolved:
  - "Symbolic HLQ is supplied by the submission profile"

Ese último campo forma parte de la documentación, no es algo vergonzoso. Le dice al equipo de migración qué artefacto debe solicitar a continuación.

Las tarjetas de control y las salidas del planificador merecen atención especial. Un paso JCL de una línea puede recibir cientos de líneas de parámetros desde un conjunto de datos mantenido fuera del control de versiones. Una salida del planificador puede reescribir variables o elegir una biblioteca de procedimientos. Trate los datos de control referenciados pero ausentes como una dependencia externa con propietario y tarea de recuperación.

Las pruebas de ejecución cambian la respuesta

La extracción estática describe lo que permite el repositorio. Las pruebas de ejecución muestran lo que hicieron ciertas ejecuciones. Ninguna vista debe hacerse pasar por la otra.

Las trazas registradas, los registros de sentencias de base de datos, los historiales de procesos, los metadatos de mensajes, los catálogos de archivos y el tráfico de producción pueden confirmar destinos dinámicos y priorizar rutas. Pueden mostrar que un despachador configurable eligió tres de veinte programas posibles durante la captura. No pueden demostrar que los otros diecisiete estén muertos. La ausencia en una traza significa "no observado en esta muestra", no "inalcanzable".

La documentación más sólida guarda por separado las aristas estáticas y observadas y después ofrece su intersección y sus diferencias. Imagine un punto de llamada con una lista configurada de destinos RATEA, RATEB y RATEC. Una traza de cierre mensual ve RATEA y RATEC. El registro correcto conserva los tres destinos posibles, marca dos como observados y registra el periodo y el entorno de captura. Borrar RATEB del grafo convertiría una prueba limitada en una afirmación falsa.

El tráfico de producción también ayuda a verificar el comportamiento durante una reescritura. Las entradas y salidas pueden convertirse en casos de paridad si la captura elimina o protege datos sensibles y conserva las variables que determinan el comportamiento. Un caso de paridad aprobado demuestra coincidencia para ese caso. No establece equivalencia general, por lo que la documentación debe expresar la cobertura por punto de entrada, rama, forma de datos y clase de error cuando esas medidas estén disponibles.

Aquí el análisis del repositorio deja de ser un índice más bonito. Un grafo estático indica dónde colocar sondas. Las trazas muestran qué aristas sin resolver merecen atención. Las diferencias entre ejecuciones antiguas y nuevas revelan comportamiento no documentado, y esos hallazgos pueden volver al almacén de pruebas.

Nunca permita que una capa de ejecución borre la base estática. Los procesos trimestrales, los controladores de fallos, las extracciones regulatorias y los procedimientos de emergencia pueden no aparecer durante una captura normal. Los equipos suelen llamarlos muertos porque la traza habitual no dice nada y descubren su propósito en el único evento en que se ejecutan.

El texto generado necesita citas y caducidad

El texto generado se vuelve fiable cuando un revisor puede cuestionar cada afirmación importante sin aplicar ingeniería inversa al generador. Coloque las referencias junto a las afirmaciones y añada la revisión de extracción, la versión de la herramienta, la configuración y la hora de generación a los metadatos del documento.

El commit del repositorio es la fecha efectiva del documento. Si cambia la rama principal, el documento generado queda obsoleto aunque su texto siga sonando plausible. Vuelva a generarlo en la integración continua o etiquételo claramente con el commit que describe. Prefiero que falle una comprobación de vigencia antes que ofrecer en silencio una mezcla de diagramas antiguos y código nuevo.

Las afirmaciones necesitan distintas clases de citas. Una afirmación estructural puede citar líneas de código. Una afirmación de ejecución debe citar un conjunto de trazas o una exportación del historial junto con su periodo de observación. Una definición de negocio debe citar un glosario aprobado, una regla, una prueba o un revisor identificado. Cuando no haya cita, marque la frase como pregunta o inferencia.

Use un pequeño registro de revisión en vez de enterrar la incertidumbre en el texto:

ID       CLAIM                                  CLASS       EVIDENCE
DOC-041  POSTINV writes AR_LEDGER               observed    post_invoice.cbl:88
DOC-042  AR_LEDGER is the accounting system     inferred    table name, 6 writers
DOC-043  CLOSE_AR may be safely restarted       unresolved  no recovery rule found

La forma de salida importa porque cambia el comportamiento del revisor. Si las tres afirmaciones se convierten en párrafos fluidos, los lectores tienden a aceptarlas juntas. El registro obliga a la afirmación débil a seguir siendo débil.

La caducidad debe ser selectiva. Un inventario de módulos se puede regenerar en cada fusión. Un significado de negocio aprobado por un operador debe persistir hasta que cambie su prueba, y el sistema debe conservar la aprobación y la fuente. Una afirmación de ejecución caduca cuando su periodo de observación deja de representar el uso actual. Un único sello de "última actualización" no puede expresar estas diferencias.

Los repositorios multilenguaje necesitan pruebas comunes

Ningún analizador puede documentar por sí solo un sistema que cruce COBOL, JCL, PL/SQL, shell, Java y macros de hoja de cálculo. Cada lenguaje necesita un componente que entienda sus declaraciones y reglas de resolución, mientras que el resultado conjunto necesita un vocabulario común para unidades, puntos de entrada, activos de datos y aristas.

La búsqueda de texto mantiene su utilidad, pero debe encontrar candidatos, no afirmar relaciones. Buscar el nombre de una tabla puede localizar SQL incrustado, comentarios, definiciones copiadas, datos de prueba y campos no relacionados con la misma ortografía. Un extractor consciente del lenguaje puede clasificar algunos resultados. Un paso de resolución posterior puede conectar una llamada con una declaración bajo la configuración de compilación correcta.

Normalice las identidades sin borrar los nombres nativos. POSTINV, un nombre de archivo fuente, un nombre de módulo cargable y una operación del planificador pueden referirse al mismo ejecutable en etapas distintas. Conserve cada identificador y añada una relación de alias respaldada por pruebas. Si el alias procede solo de una convención de nombres, márquelo como inferido. Fusionar identidades demasiado pronto genera aristas falsas difíciles de separar después.

Las conexiones entre lenguajes suelen aparecer en protocolos y artefactos, no en símbolos. Un proceso COBOL escribe un archivo plano que lee un script Perl. Un cliente VB6 invoca una interfaz COM implementada en Delphi. Un procedimiento almacenado escribe en una tabla de cola consultada por un servicio. Modele el archivo, la interfaz, la tabla o el mensaje como nodo propio. Conectar directamente ambos programas ocultaría el contrato que realmente los acopla.

El código generado necesita dos registros: la entrada del generador y el artefacto emitido que utiliza la compilación. Analizar solo las plantillas pierde el comportamiento emitido, mientras que analizar solo los archivos generados oculta la propiedad y la regeneración. La documentación debe mostrar qué archivo se puede editar y cuál se sobrescribirá.

Los repositorios grandes añaden un problema de escala, no un problema distinto de verdad. Analice los archivos de forma incremental, almacene resultados identificados por contenido y vuelva a calcular las aristas afectadas cuando cambien declaraciones o configuraciones. No reduzca el alcance muestreando directorios para llamar mapa del sistema al resultado. Un árbol de un millón de líneas se puede procesar por partes, pero sus referencias entre límites todavía deben resolverse frente al inventario completo.

La verificación por muestras puede ser profunda

Un equipo puede probar la documentación generada sin volver a leer manualmente todo el repositorio. La verificación debe muestrear por riesgo y tipo de arista y después usar invariantes automáticos para detectar clases amplias de fallos de extracción.

Empiece por casos de prueba del analizador. Dé a cada extractor de lenguaje ejemplos pequeños de llamadas directas, alias, compilación condicional, despacho dinámico, inclusiones, entradas mal formadas y comentarios con texto parecido a código. Compruebe las aristas que debe emitir y las aristas falsas y tentadoras que debe rechazar. Conserve fallos reales reducidos como casos de regresión.

Ejecute invariantes para todo el repositorio después de la extracción. Cada archivo y línea citados deben existir en el commit analizado. Cada destino resuelto de llamada debe tener una declaración o identidad externa explícita. Cada miembro de módulo debe existir en el inventario. Cada tipo de arista debe utilizar tipos de origen y destino permitidos. Estas comprobaciones no demuestran significado, pero detectan uniones rotas y ubicaciones obsoletas antes de que las vea un revisor.

Después elija muestras de revisión desiguales. Inspeccione todas las aristas desconocidas en puntos de entrada importantes, todas las escrituras entre módulos, todas las condiciones del planificador y una selección aleatoria de llamadas estáticas normales. Muestree también el espacio negativo: elija mecanismos dinámicos conocidos y confirme que el documento muestra su incertidumbre. Medir la exactitud solo con llamadas directas fáciles recompensa al sistema equivocado.

Un informe compacto de aceptación puede incluir cifras útiles sin convertirlas en una puntuación de calidad:

Analyzed commit: 7c41e2f
Parsed files: 18,442 of 18,517 discovered
Skipped files: 75 (list attached to the evidence store)
Resolved call edges: 91,208
Unknown dispatch sites: 613
Broken citations: 0
Scheduler sources: repository JCL only; current-plan export absent

Las cifras son un ejemplo del formato de salida, no un valor de referencia. Las líneas importantes son el denominador, la lista de archivos omitidos y la fuente ausente del planificador. Informar de "18.442 archivos analizados" sin decir que 75 se omitieron permite que un analizador fallido desaparezca dentro de un gran total.

Las correcciones de revisión deben actualizar reglas o pruebas, no solo el párrafo mostrado. Si un revisor detecta un alias falso, añada una restricción que impida la fusión la próxima vez. Si un operador confirma una definición de negocio, guarde la aprobación como fuente independiente. De otro modo, la regeneración reproducirá con fidelidad cada error ya corregido.

La confianza se rompe en los límites dinámicos y humanos

La documentación automatizada deja de ser fiable en límites donde el repositorio carece de la información decisiva. Los principales son la selección dinámica, el estado externo, el código generado o ausente, la intervención operativa, la configuración específica del entorno y la intención de negocio.

Puede convertir esa afirmación en una lista de revisión:

1. Resuelva cada artefacto referenciado. Busque archivos incluidos, fuentes generadas, bibliotecas de procedimientos, tarjetas de control, esquemas y manifiestos de despliegue. Registre todo lo que falte.
2. Compare la compilación real con la disposición del repositorio. Capture opciones del compilador, símbolos condicionales, pasos de generación de código y unidades exactas desplegables.
3. Superponga pruebas de ejecución sin tratarlas como exhaustivas. Mantenga el periodo de muestra y el entorno junto a cada arista observada.
4. Pregunte a operaciones por reinicios, cortes, sustituciones y rutas de excepción. Esas reglas suelen vivir en manuales, consolas del planificador o en la memoria.
5. Exija una fuente identificada para las etiquetas de negocio. Una expansión plausible de un nombre de campo de ocho caracteres sigue siendo una suposición.

Una recomendación popular consiste en pedir a un modelo de lenguaje que lea el repositorio y escriba un manual de arquitectura completo de una vez. Es popular porque el primer resultado llega rápido y parece coherente. Es errónea porque la coherencia elimina las costuras visibles entre hechos analizados, interpretaciones y omisiones. Use un modelo para explicar un grafo, agrupar pruebas y redactar preguntas, pero mantenga el grafo de pruebas como autoridad.

Los límites de seguridad y acceso pueden crear otro punto ciego. Un analizador que no pueda leer exportaciones del planificador de producción, configuraciones cifradas o catálogos de base de datos debe decirlo al principio. La falta de acceso no debe convertirse en ausencia de una dependencia.

La prueba práctica de aceptación es sencilla: seleccione afirmaciones al azar y siga sus citas. Si los revisores no pueden reproducir las afirmaciones estructurales, el sistema no está listo. Si pueden reproducirlas pero discrepan del texto, corrija la regla de inferencia o la redacción sin descartar las pruebas extraídas.

La documentación debe dirigir el plan de reescritura

La documentación del repositorio justifica su coste cuando cambia la secuencia, las pruebas y el alcance. Un mapa de módulos debe identificar unidades sustituibles por separado y nudos de estado compartido. Un grafo inverso de llamadas debe revelar llamadores que necesitan cobertura de compatibilidad. El modelo de datos debe identificar disputas de propiedad y acoplamiento oculto. El grafo batch debe exponer cortes y rutas de recuperación que una reescritura como servicios debe conservar.

Para planificar la migración, consulte las pruebas en vez de leerlas de principio a fin. Pregunte qué puntos de entrada llegan a un módulo candidato, qué tablas cruzan el límite propuesto, qué procesos por lotes lo invocan y qué aristas siguen sin resolverse. Una arista sin resolver asociada a una ruta diaria de liquidación merece atención antes que una utilidad de informes totalmente cartografiada, aunque la utilidad tenga más líneas.

La modernización de la arquitectura también exige una base de comportamiento. Traducir cada programa antiguo a un lenguaje nuevo conserva límites accidentales y hace familiares los diagramas generados, pero la familiaridad es un criterio de diseño pobre. Use puntos de entrada observados, contratos de datos, efectos secundarios y restricciones de orden para definir la compatibilidad. Después diseñe los servicios de destino alrededor de una propiedad coherente.

CodeHero aplica esta combinación al reescribir sistemas antiguos: su plataforma lee todo el árbol multilenguaje y un banco de paridad compara el sustituto con tráfico de producción registrado. Eso no convierte el propósito inferido en un hecho. Da funciones distintas a la extracción estructural y a las pruebas de comportamiento, que es la disciplina necesaria para una reescritura.

Antes de aprobar un documento generado, exija respuesta a una pregunta concreta: ¿qué afirmaciones cambiarían si mañana llegara la exportación del planificador, la traza de ejecución o la entrevista con operaciones? Si el documento no puede identificarlas, ha ocultado la incertidumbre en vez de gestionarla. Un repositorio puede producir un mapa excelente, pero las zonas en blanco deben seguir visibles hasta que las pruebas las llenen.

Conserve el inventario de pruebas después de entregar la reescritura. Se convierte en un oráculo de regresión para cambios de dependencias, una fuente de documentación operativa y un control contra nuevo acoplamiento accidental. El texto puede envejecer, pero los hechos reproducibles vinculados a commits se pueden regenerar cada vez que cambie el sistema.