2026-06-26 Reflexión

Hoy, al documentar el flujo de entrada source-to-AST, organicé cómo “pasar realmente el código fuente al juicio del LLM”.

No fue solo un día de escribir documentación. También estaba recopilando datos relacionados con Godot en tiempo real, así que la documentación no podía quedar solo como un diseño abstracto. Necesitaba un criterio para verificar por qué ruta pasan los datos recopilados, en qué unidades se fragmentan y a qué solicitudes deben conducir.

¿Por qué quería organizar este diseño primero?

Quise documentar este diseño primero porque, en trabajos anteriores, había la inquietud de que la IA pudiera escribir código de forma extraña o cambiar arbitrariamente el alcance de la solicitud.

En particular, me preocupaba que, al tener que enviar todo el Markdown, se implementara enviando solo una parte inicial, o que se insertara código hardcodeado que no deseaba, o que, aunque se necesitara ver todo el archivo, solo se enviara el “código clave”.

Por eso, antes de escribir código, quise fijar en un documento: “qué solicitud hacer a la IA”, “en qué unidades desplegar el archivo”, “qué poner en el AST Parser y qué pasar directamente al Retriever”, “qué combinaciones deben usarse en la llamada al LLM”.

Hoy en día, más que la implementación misma, me preocupa cómo dar instrucciones a la IA para que la intención se distorsione lo menos posible. El mismo requerimiento puede dar resultados muy diferentes según cómo se delimite el alcance, qué expresiones se prohíban y qué evidencias se soliciten.

Este documento es más una línea base para que, al delegar la implementación a la IA, la solicitud no se difumine. Es una reflexión previa para evitar que la IA reduzca la entrada arbitrariamente, envíe solo el código clave o modifique archivos no solicitados.

Criterio actual

Considero que el código fuente debe desplegarse con encabezados del tipo # <ruta_relativa>/<ruta_relativa>. El propósito de este encabezado no es adornar el prompt, sino rastrear de dónde proviene el archivo y en qué fragmentos se divide antes de pasar al Retriever.

Desde el principio, pensé en desplegar el repositorio de GitHub en orden de rutas, excluir los archivos que correspondan y mostrar en la UI web o en logs qué se ha excluido. Luego, los archivos restantes se dividirían en unidades legibles y se rastrearía de qué archivo original proviene cada fragmento.

Durante la documentación, la IA malinterpretó repetidamente la dicotomía “¿enviar todo el archivo de una vez o solo el código clave?”. Lo que yo imaginaba era desplegar el archivo por ruta y luego enviarlo fragmentado y ordenado.

En mi criterio, los archivos .gd son los que ingresan al AST Parser. El AST Parser debe extraer secuencialmente unidades parseables como la función a, la función b, la función c y la función d dentro de .gd. Si la unidad de función es ambigua, basta con fragmentar por trozos de código en orden. La clave no es “seleccionar arbitrariamente funciones clave”, sino fragmentar manteniendo el orden y la ruta original y rastrear cómo esos fragmentos llegan al Retriever.

Por el contrario, los archivos como .md que decidimos excluir del análisis deben quedar en la lista de exclusión. Es crucial que el hecho de exclusión no desaparezca. Se debe mostrar en la UI web o en logs por qué y bajo qué criterio se excluyó cada archivo. Si existen archivos de configuración de texto que no deben pasar por el AST Parser, lo natural es dividirlos en líneas, párrafos, pares clave‑valor, nodos/recursos/conexiones, y enviarlos directamente al Retriever.

En resumen, el flujo actual se asemeja a lo siguiente.

repository path order
  -> "# <relative/path>" file expansion for tracking
  -> excluded file list visible in UI/log
  -> .gd files to AST Parser
  -> AST Parser emits ordered function/code chunks
  -> excluded files are recorded with reason
  -> non-.gd allowed text/config files emit ordered chunks
  -> each chunk goes to Retriever with source path metadata
  -> prompt + current chunk + retrieved evidence
  -> LLM judgment
  -> validation
  -> accumulated project-level result

Parte reparada de la interpretación de IA

En el medio, la IA creó una estructura separada como repository_file_manifest, pero eso no coincidía con la dirección que yo imaginaba. Lo que se necesita no es un repositorio de manifiestos separado, sino rastrear, a partir del flujo de archivos desplegado con encabezados # <ruta relativa>, qué archivos fueron excluidos, en qué fragmentos se dividieron y en qué orden esos fragmentos ingresaron al Retriever.

Resulta extraño decir que “no se leen” los binarios o los assets. Lo esencial es que no se insertan los bytes originales en el LLM; eso no significa que el archivo desaparezca por completo del juicio del proyecto. Si dentro de fragmentos de texto como .tscn, .import, README aparece una ruta de asset, basta con juzgar a partir de ese fragmento.

Otro aspecto que sentí necesario es la depuración de la transmisión. No debe fluir que la IA seleccione y envíe solo las funciones clave de un archivo .gd. Los archivos desplegados con # <ruta relativa> deben poder dividirse en el AST Parser en fragmentos de función/código, y debe ser posible verificar, mediante diff o SHA‑256, cuál fragmento pasó al Retriever y en qué posición.

Puntos organizados al revisar el PR

Al revisar el PR, me di cuenta de que llm_judgment_request estaba definido de dos maneras diferentes dentro del documento. Una versión se centraba en chunk_text, chunk_kind y retrieved_evidence, mientras que la otra incluía también chunk_code, surrounding_context y judgment_contract.

Cuando el mismo objeto de solicitud se define de forma distinta en el documento, es inevitable que haya confusión al implementarlo más adelante. El esquema de solicitud debe unificarse. En particular, para distinguir entre chunks de AST y chunks de recuperación directa, se necesita chunk_kind; y para validar el juicio del LLM, también deben estar claros retrieved_evidence y judgment_contract.

En la revisión de Qwen se señaló un enlace al README, errores tipográficos y enlaces relacionados con el documento del día 25. Sin embargo, el documento del día 25 o el workflow no fueron parte del cambio que yo pretendía en el diff del PR. La IA introdujo modificaciones arbitrarias, y después de detectarlas solicité que se restaurara el estado original.

Alcance mezclado del problema

Hoy descubrí en el diff del PR que se incluyeron el documento del 25 y .github/workflows/qwen-code-pr-review.yml. Eso no era el cambio que solicité. Parecía que la IA había modificado o eliminado archivos arbitrariamente, y en la pantalla del PR parecía que los siguientes archivos habían sido modificados o eliminados.

• .github/workflows/qwen-code-pr-review.yml
• docs/observations/2026-06-25-qwen-markdown-classification-observation.md
• docs/retrospectives/2026-06-25-source-analysis-scoring.md
• docs/roadmaps/2026-06-25-qwen-pr-review-workflow.md

Así que exigí que se revertieran esos cambios. Después, esos archivos fueron restaurados según origin/main, y el diff del PR se centró en README.md y docs/roadmaps/2026-06-26-source-to-ast-input-flow.md.

Al observar este proceso, pensé que, incluso cuando se delega la redacción de documentos a la IA, es necesario fijar firmemente el alcance de los cambios de antemano. Escribir retrospectivas o documentos de hoja de ruta también debe gestionarse como el alcance de un PR, al igual que los cambios de código.

Conclusión del día

Lo que confirmé nuevamente hoy es que el punto clave es “cómo se excluyen los archivos desplegados por ruta, en qué fragmentos se dividen y en qué orden esos fragmentos pasan al Retriever y al juicio del LLM”. No se trata de insertar todos los archivos de una vez, ni de seleccionar arbitrariamente solo el código esencial.

Actualmente, el criterio se establece de la siguiente manera:

• Los archivos se despliegan con un encabezado # <ruta relativa>, y este encabezado se usa para rastrear la ruta original y los fragmentos.
• Los archivos excluidos deben poder verse en la interfaz web o en los registros.
• Los archivos .gd se envían al AST Parser, y el AST Parser genera funciones o fragmentos de código en el orden original.
• Los archivos que se decidieron excluir, como .md, se dejan en la lista de exclusión y deben poder verse en la interfaz web o en los registros.
• Los archivos de configuración de texto que no se excluyen se fragmentan en unidades como líneas, párrafos o bloques de configuración sin pasar por el AST.
• Cada fragmento lleva información de seguimiento como la ruta de origen y el orden del fragmento al pasar al Retriever.
• Las llamadas al LLM se realizan varias veces en la unidad prompt + fragmento actual + resultados de búsqueda del Retriever.
• Se consideró que la evaluación del proyecto solo es posible después de que se acumulen los resultados de juicio de varios fragmentos desde el principio.

La recopilación de datos sigue en curso. Por lo tanto, los documentos futuros deben servir como criterio para verificar no solo una “arquitectura plausible”, sino también cómo los datos recopilados realmente ingresan y se validan.