AgainstWar/HDL-Repair-Skills

Reparación Mínima de HDL y Verificación de Consistencia

Un flujo de trabajo para generar el parche seguro más pequeño que corrija un error de diseño HDL, y luego verificar que la corrección no rompa contratos de hardware ni deje inconsistencias entre artefactos.

Qué Cubre Esta Habilidad

Esta habilidad es la mitad de reparación de un pipeline de dos habilidades (localización → reparación). Acepta dos vías de entrada:

1. Con una Nota de Hipótesis de Causa Raíz (de hdl-fault-localization o equivalente) — analizar la nota, seleccionar la mejor hipótesis y proceder.
2. Con una intención de reparación existente — cuando el usuario o un agente previo ya ha proporcionado una ubicación específica del fallo, dirección de corrección o diff de parche, promover esa intención a una hipótesis provisional y proceder.

La habilidad hace cuatro cosas y nada más:

1. Planificación del parche mínimo — el conjunto más pequeño de cambios que abordan la hipótesis seleccionada, sin modificaciones no relacionadas.
2. Escáner de efectos secundarios — revisión de pares de contratos de hardware (ready/valid, reset/flush/replay, transiciones de FSM, estado obsoleto, ordenamiento de pipeline).
3. Verificador de enlaces entre artefactos — asegurar que configuraciones, archivos generados, descripciones de registros y scripts de generación se mantengan consistentes.
4. Verificación de pruebas — ejecutar la suite de pruebas y manejar fallos mediante hipótesis de respaldo.

Esta habilidad NO realiza localización de fallos. Si el fallo no ha sido localizado, detenerse y requerir localización primero.

Cuándo Usar Esta Habilidad

Esta habilidad se activa solo cuando el problema ya ha sido localizado. Cualquiera de los siguientes es suficiente para ingresar:

• Se proporciona una Nota de Hipótesis de Causa Raíz (de hdl-fault-localization o equivalente).
• El usuario o un agente previo ha dado una ubicación explícita del fallo (archivo, módulo, señal) y dirección de corrección (qué cambiar y por qué).
• El usuario ha indicado una intención de reparación clara (por ejemplo, "ampliar este puntero", "agregar un búfer skid", "corregir la transición de FSM").
• Existe un diff de parche que necesita revisión por efectos secundarios o consistencia.

Si ninguna de estas señales de entrada está presente — el fallo no está localizado, no existe hipótesis y no hay una intención de reparación específica que promover — detenerse y requerir localización primero. No intente diagnosticar el fallo; esa es responsabilidad de una habilidad separada de localización de fallos. Solicitudes vagas como "arreglar este error", "algo está mal" o "mi testbench falla" sin información de localización NO son señales de entrada — carecen de la especificidad requerida para el alcance de solo reparación de esta habilidad.

Frases típicas de activación: "aplicar la corrección", "hacer el parche", "implementar la reparación", "revisar este parche por efectos secundarios", "verificar contratos de hardware después de este cambio", "auditar consistencia entre artefactos".

Requisitos de Entrada

Al menos uno de los siguientes debe estar presente antes de comenzar. Si ninguno existe, detenerse y requerir localización primero.

1. Nota de Hipótesis de Causa Raíz — un archivo o texto en línea que describa una o más hipótesis, cada una con fuerza de evidencia y justificación. Esta es la entrada preferida y es producida por hdl-fault-localization.
2. Ubicación explícita del fallo + dirección de corrección — el usuario o un agente previo ha identificado un archivo, módulo o señal específico y describió qué cambio hacer. Promover esta intención de reparación a una hipótesis provisional.
3. Intención de reparación existente — un plan indicado (por ejemplo, "ampliar el puntero de 4 a 5 bits") que puede tratarse como una nota de hipótesis única.
4. Diff de parche existente — un cambio de código propuesto para revisar por efectos secundarios y consistencia de artefactos.

Adicionalmente, recopilar:

• Archivos fuente relevantes — rutas a los módulos HDL, testbenches y código de soporte involucrados.
• Comando de prueba — el comando exacto para ejecutar la suite de pruebas.
• Registros de fallos — opcional pero recomendado para contexto.

Flujo de Trabajo Principal

Siga estos pasos en orden. Cada paso produce una salida que alimenta al siguiente.

Paso 0: Verificación de Puerta de Entrada (ANTES de cualquier análisis de código)

Antes de leer cualquier archivo fuente, registro o forma de onda, verificar que al menos una señal de entrada esté presente en el mensaje del usuario. Verificar en este orden:

1. ¿Hay una Nota de Hipótesis de Causa Raíz (una ruta de archivo, YAML en línea o texto estructurado con hipótesis etiquetadas y evidencia)?
2. ¿El usuario ha especificado una ubicación concreta del fallo y dirección de corrección (un archivo, módulo o señal específico Y una descripción de qué cambio hacer — no solo "arréglalo" o "algo está mal")?
3. ¿El usuario ha indicado una intención de reparación específica (por ejemplo, "ampliar el puntero a 5 bits", "agregar un búfer skid", "cambiar la transición de FSM de A a B")?
4. ¿Hay un diff de parche existente para revisar?

Si NINGUNO de estos está presente — el usuario dice solo "arreglar este error", "mi testbench falla", "algo está mal" o solicitudes vagas similares sin localización — detenerse inmediatamente. No leer el código fuente. No intentar diagnosticar el fallo. Salida:

Esta habilidad requiere localización previa. Ejecute la localización de fallos
primero (hdl-fault-localization), o proporcione uno de:
- Una Nota de Hipótesis de Causa Raíz
- Una ubicación explícita del fallo (archivo/módulo/señal) y dirección de corrección
- Una intención de reparación específica (qué cambiar y por qué)
- Un diff de parche existente para revisar

Solo proceder al Paso 1 después de confirmar que una señal de entrada está presente.

Paso 1: Establecer la Hipótesis de Reparación

Si una Nota de Hipótesis de Causa Raíz formal está disponible, analizarla para extraer:

• Cada hipótesis, etiquetada y descrita.
• La evidencia que respalda cada hipótesis (fuerte, moderada, débil).
• La dirección de corrección sugerida para cada hipótesis.
• Cualquier orden de respaldo o dependencia entre hipótesis.

Si la nota contiene múltiples hipótesis, listarlas todas. Si contiene solo una, eso simplifica la selección — pero aún evaluar su fuerza de evidencia antes de comprometerse.

Si no se proporciona una nota de hipótesis pero existe una intención de reparación (ubicación explícita del fallo + dirección de corrección, un plan de reparación indicado o un diff de parche existente), promover esa intención a una hipótesis provisional. Darle una etiqueta (por ejemplo, "P1-sync-fifo-pointer-widen") y documentar la evidencia que la respalda de la descripción del usuario. Esta hipótesis provisional se trata como la única hipótesis para los Pasos 2-7. No intentar generar hipótesis alternativas ni realizar localización de fallos — el alcance de esta habilidad termina en la ejecución de la reparación.

Paso 2: Seleccionar la Mejor Hipótesis para Parchear Primero

No todas las hipótesis son iguales. Aplicar estos criterios de selección:

1. Fuerza de evidencia — preferir hipótesis con evidencia concreta (trazas de forma de onda, patrones de registro, condiciones reproducibles) sobre las especulativas.
2. Riesgo del parche — preferir hipótesis cuya corrección está localizada (uno o dos módulos, sin cambios estructurales) sobre aquellas que requieren reescrituras amplias.
3. Reversibilidad — preferir hipótesis cuyo parche es fácil de revertir si no funciona.
4. Orden de dependencia — si la Hipótesis B depende de que la Hipótesis A sea correcta, parchear A primero.

Documentar por qué se eligió esta hipótesis sobre las alternativas. Si no se puede decidir entre dos hipótesis igualmente fuertes, elegir la de menor riesgo de parche y anotar la otra como respaldo principal.

Paso 3: Generar un Plan de Parche Mínimo

Un "parche mínimo" no significa "cambiar solo un archivo." Significa: el conjunto más pequeño de cambios que abordan correctamente la hipótesis seleccionada, sin modificaciones no relacionadas.

Para cada archivo que planea modificar, responder:

• ¿Por qué debe cambiar este archivo? — rastrear la cadena causal desde la hipótesis hasta este cambio específico.
• ¿Qué cambia exactamente? — describir el cambio a nivel de señal/lógica, no detalles de implementación.
• ¿Por qué es este el cambio mínimo? — explicar por qué un cambio más pequeño sería insuficiente o un cambio más grande innecesario.

Rechazar cualquier cambio que:

• Sea cosmético (formato, renombrado, actualizaciones de comentarios no relacionados con el error).
• Sea una refactorización ("ya que estoy aquí, déjame limpiar esto").
• Codifique una expectativa de prueba para que una prueba pase.
• Modifique un archivo de prueba sin evidencia de que la prueba en sí esté mal.

Paso 4: Ejecutar el Escáner de Efectos Secundarios

Los diseños de hardware tienen contratos implícitos entre señales. Cambiar un lado de un contrato a menudo rompe el otro lado. Antes de aplicar el parche, escanear estas violaciones de contrato:

Pares ready/valid

Para cada par de handshake ready/valid en el módulo modificado y sus vecinos inmediatos:

• ¿El parche cambia cuándo se afirma o desactiva valid? Si es así, ¿la lógica ready del consumidor sigue funcionando correctamente?
• ¿El parche cambia cuándo se muestrea o impulsa ready? Si es así, ¿la lógica valid del productor sigue teniendo sentido?
• ¿Se maneja correctamente la contrapresión — puede el pipeline detenerse sin perder datos?

reset/flush/replay

Para cada señal de reset, flush o replay:

• ¿El parche cambia qué estado se limpia o conserva en el reset?
• ¿Un camino de flush todavía drena o invalida correctamente los datos en vuelo?
• ¿Un camino de replay todavía restaura el estado al punto de control correcto?

Integridad de transiciones de FSM

Para cada máquina de estados finitos afectada por el parche:

• ¿Todos los estados son alcanzables desde el reset?
• ¿Puede la FSM bloquearse (sin salida válida de un estado)?
• ¿Puede la FSM tener un bucle infinito (bucle infinito entre estados sin progreso)?
• ¿El parche agrega o elimina alguna transición de estado? Si es así, verificar que la nueva tabla de transiciones esté completa.

Estado obsoleto

• ¿El parche introduce algún registro o señal que pueda contener un valor obsoleto a través de transacciones o ciclos de reloj donde debería limpiarse?
• ¿El parche depende de que una señal sea limpiada por un mecanismo que ya no se activa correctamente?

Ordenamiento de pipeline

• ¿El parche cambia el orden de las operaciones en un pipeline? Si es así, ¿las etapas posteriores aún reciben datos en el orden esperado?
• ¿El parche cambia la profundidad del pipeline (etapas agregadas o eliminadas)? Si es así, ¿se ajustan todos los caminos de bypass y reenvío?

Documentar hallazgos para cada categoría, incluso si el resultado es "no se encontraron problemas."

Paso 5: Ejecutar el Verificador de Enlaces entre Artefactos

Los proyectos HDL a menudo tienen archivos de configuración, mapas de registros y código generado que deben mantenerse sincronizados con la fuente HDL. Verificar estos enlaces:

Archivos de configuración

Escanear archivos de configuración (YAML, HJSON, JSON, TOML, INI o similares) que hagan referencia a las señales, parámetros o módulos afectados por el parche. Si el parche cambia un valor de parámetro, nombre de módulo o lista de puertos, actualizar la configuración para que coincida.

Archivos generados

Verificar si algún archivo en el proyecto es generado automáticamente (por generadores de código, scripts o pasos de compilación). Si el parche cambia una fuente que alimenta un generador, ya sea:

• Regenerar los archivos de salida, o
• Marcar la inconsistencia para regeneración manual.

Descripciones de registros

Si el diseño incluye un mapa de registros (CSV, XML, IP-XACT, SystemRDL o similar), verificar que las posiciones de los campos de registro, anchos y tipos de acceso no se hayan desviado del HDL después del parche.

Scripts de generación

Verificar scripts Python, Perl, Tcl o shell que generen HDL o archivos de configuración. Si el parche cambia un patrón del que dependen estos scripts (convenciones de nomenclatura, anchos de señal, protocolos de interfaz), los scripts pueden producir salida rota.

Documentar todos los artefactos verificados y cualquier inconsistencia encontrada.

Cuando el parche cambia solo lógica interna (sin interfaces públicas, parámetros, campos de registro, mapas de direcciones, fuentes generadas o comportamiento visible en la configuración), la verificación de enlaces entre artefactos se reduce a "no aplicable — parche interno sin impacto entre artefactos." Evitar escanear todo el árbol del proyecto en busca de artefactos que no puedan ser afectados por el cambio. Ejecutar una búsqueda completa de artefactos solo cuando el parche toque una de las superficies listadas anteriormente.

Paso 6: Aplicar el Parche y Ejecutar Pruebas

Aplicar el parche a los archivos fuente reales. Luego ejecutar el comando de prueba:

1. Ejecutar la suite de pruebas una vez.
2. Si todas las pruebas pasan — documentar el resultado y proceder al Paso 7.
3. Si algunas pruebas fallan — analizar:
   • ¿Son fallos preexistentes? Verificar registros de fallos para ver si estas pruebas fallaban antes del parche. Los fallos preexistentes no son culpa del parche — anotarlos pero no bloquear la corrección.
   • ¿Son fallos causados por el parche? Si el parche introdujo nuevos fallos, la corrección está incompleta o es incorrecta. Ir a la ruta de respaldo.
   • ¿Los fallos revelan un error de prueba? Solo concluir esto si se tiene evidencia concreta de que la expectativa de prueba es incorrecta, no solo porque el parche cambió el comportamiento.

Paso 7: Manejar Fallos — Retroceder a la Siguiente Hipótesis

Si el parche falla las pruebas de una manera causada por el parche (no preexistente o error de prueba):

1. No intentar salvar el parche con ajustes ad-hoc. Eso convierte una corrección basada en hipótesis en adivinanzas.
2. Si el entorno de ejecución soporta reversión limpia (por ejemplo, git checkout, git stash o un gestor externo que maneje el estado del parche), revertir el parche fallido antes de probar el respaldo. Si la reversión no es compatible, inspeccionar y deshacer explícitamente las ediciones fallidas antes de continuar — no superponer un nuevo parche sobre uno roto.
3. Seleccionar la siguiente hipótesis de la nota de hipótesis (la que tenga la siguiente mejor combinación de evidencia y riesgo).
4. Documentar en la Nota de Decisión de Parche: qué hipótesis falló, por qué (qué prueba se rompió) y qué hipótesis se está probando ahora.
5. Volver al Paso 2 con la hipótesis de respaldo.

Si todas las hipótesis se agotan y ningún parche pasa las pruebas, informar que el conjunto de hipótesis es insuficiente — la causa raíz puede no estar capturada por ninguna de las explicaciones hipotéticas.

Salida: Nota de Decisión de Parche

Al final del flujo de trabajo (ya sea que el parche haya tenido éxito o no), producir una Nota de Decisión de Parche usando esta estructura exacta:

patch_decision_note:
  selected_hypothesis: <qué hipótesis fue parcheada>
  patch_scope: <resumen de una oración de lo que cambia el parche>
  modified_files:
    - <ruta del archivo>: <razón por la que este archivo tuvo que cambiar>
    - <ruta del archivo>: <razón por la que este archivo tuvo que cambiar>
  side_effects_scan:
    ready_valid: <hallazgos o "sin problemas">
    reset_flush_replay: <hallazgos o "sin problemas">
    fsm_transitions: <hallazgos o "sin problemas">
    stale_state: <hallazgos o "sin problemas">
    pipeline_ordering: <hallazgos o "sin problemas">
  artifact_links_checked:
    config_files: <archivos verificados o "no aplicable">
    generated_files: <archivos verificados o "no aplicable">
    register_descriptions: <archivos verificados o "no aplicable">
    generator_scripts: <archivos verificados o "no aplicable">
  test_results:
    command: <comando de prueba exacto ejecutado>
    passed: <número de pruebas pasadas>
    failed: <número de pruebas fallidas>
    pre_existing_failures: <lista o "ninguno">
    patch_caused_failures: <lista o "ninguno">
    test_bugs_discovered: <lista o "ninguno">
  final_status: <"éxito" o "fallo — hipótesis agotadas">
  fallback_history:
    - hypothesis: <etiqueta de la hipótesis de respaldo si se usó>
      failure_reason: <por qué falló el parche>

Notas Finales

• Esta habilidad es intencionalmente estrecha. No localiza fallos, no refactoriza código, no mejora el rendimiento a menos que esté directamente relacionado con la hipótesis de corrección y no agrega características. Cualquier solicitud de este tipo debe ser rechazada o redirigida a la habilidad o agente apropiado.
• La Nota de Decisión de Parche es la única salida canónica. Si un paso produce información intermedia (como hallazgos del escáner de efectos secundarios o inconsistencias entre artefactos), debe incorporarse en la nota final, no como una salida separada.
• Cuando trabaje con archivos generados, prefiera marcar la inconsistencia para regeneración manual sobre regenerar automáticamente, a menos que el entorno de ejecución garantice que la regeneración es segura y reproduce exactamente lo que produciría el proceso de compilación.
• La reversión debe ser verificada antes de aplicar un nuevo parche. Si el sistema de archivos está en un estado inconsistente (parche a medio aplicar, ediciones no guardadas), no se puede confiar en la secuencia de prueba de respaldo.