Atlas-KK/repo-grounded-change

Cambio Basado en Repositorio

Convierte una solicitud de optimización para un proyecto existente en un cambio confirmado y listo para implementar, y luego ejecuta solo la opción aprobada.

Contrato de interacción y autorización

• Inspecciona el repositorio actual antes de recomendar una solución. No preguntes al usuario por hechos que se puedan descubrir a partir del código, las pruebas, la configuración o los documentos de producto aplicables.
• Permanece en modo solo lectura hasta que el usuario apruebe explícitamente una opción o una línea base de modificación. Los diagnósticos y la inspección del repositorio no autorizan ediciones.
• No impongas este flujo de trabajo a una solicitud de implementación directa y sin ambigüedades. Utiliza la compuerta cuando el usuario pida primero una evaluación o cuando una elección afecte materialmente el comportamiento, la compatibilidad, el riesgo o el alcance.
• Haz solo preguntas que impliquen decisiones. Utiliza un control de entrada de usuario estructurado cuando esté disponible; de lo contrario, usa códigos de opción concisos como Q1-A.
• Normalmente, ofrece 2 o 3 opciones factibles mutuamente excluyentes. Coloca la opción recomendada primero y explica por qué. Si solo existe una opción segura, explica por qué se rechazaron las alternativas en lugar de inventar opciones falsas.
• Después de la confirmación, implementa la opción seleccionada sin agregar silenciosamente limpieza no relacionada. Si nuevos hechos del repositorio cambian materialmente el comportamiento aprobado, el alcance, la migración, las dependencias o los criterios de aceptación, detente y pide una decisión revisada.

Evidencia y etiquetas de decisión

Mantén los hechos separados de la interpretación:

• objetivo del usuario: el punto débil y el resultado expresado por el usuario.
• hecho de código: comportamiento observado en el código fuente actual, pruebas, tiempo de ejecución o configuración.
• hecho de documentación: comportamiento requerido por el documento de producto aprobado aplicable.
• recomendación técnica: una recomendación de implementación que preserva el comportamiento previsto del producto.
• suposición de producto: una suposición reversible que requiere confirmación.
• pendiente de confirmar: una elección no resuelta que impide la implementación.
• confirmado: la opción o línea base aprobada explícitamente por el usuario.
• no se cambia ahora: comportamiento o código intencionalmente fuera del cambio aprobado.

A menos que el usuario especifique lo contrario, usa este orden de autoridad:

1. Instrucciones explícitas actuales del usuario.
2. Decisiones confirmadas explícitamente en la tarea actual.
3. La especificación de producto aprobada aplicable.
4. Código y pruebas actuales para el comportamiento existente.
5. Archivos README y documentos históricos.

Expón los conflictos; no elijas silenciosamente una fuente.

Flujo de trabajo

1. Descubre el comportamiento actual

Lee references/discovery-and-impact.md. Inspecciona solo las áreas del repositorio necesarias para reproducir o explicar el punto débil. Protege los cambios existentes del usuario y establece la línea base de pruebas actual cuando sea proporcionado.

Reporta el comportamiento actual, el impacto en el usuario, los límites de código relevantes y la evidencia faltante antes de presentar las opciones.

2. Aclara el objetivo del cambio

Traduce la solicitud en resultados observables y restricciones. Aclara solo los problemas que puedan cambiar la opción, el alcance, la estrategia de compatibilidad o el resultado de aceptación.

No trates el texto literal de la interfaz de usuario como un mecanismo de implementación requerido cuando esto introduzca semánticas de interacción incorrectas. Explica la distinción y ofrece una opción compatible con el repositorio.

3. Compara opciones factibles

Lee references/options-and-clarification.md. Compara el impacto en producto e ingeniería, incluyendo experiencia de usuario, comportamiento preservado, compatibilidad de estado y datos, accesibilidad, impacto en pruebas, esfuerzo de implementación, dificultad de reversión y riesgos significativos.

4. Genera la especificación de cambio recomendada

Lee references/change-spec-and-acceptance.md. La opción recomendada debe ser directamente ejecutable por Codex e incluir:

• comportamiento e interacción objetivo;
• módulos, componentes, archivos, interfaces y estado afectados;
• manejo de compatibilidad, persistencia, migración, degradación y reversión cuando sea relevante;
• comportamiento y datos que deben preservarse;
• exclusiones explícitas;
• plan de pruebas y criterios de aceptación observables.

No modifiques el código en este paso.

5. Obtén aprobación explícita

Presenta la recomendación y las elecciones restantes. Detente después de pedir al usuario que seleccione una opción o responda la ronda de aclaración más pequeña necesaria.

Después de la respuesta, resume la opción confirmada, las modificaciones del usuario, los asuntos no resueltos, los impactos posteriores y la línea base de aceptación final. Comienza la implementación solo cuando la respuesta autorice claramente la ejecución, como confirmar opción A o ejecutar según la recomendación.

6. Implementa la opción aprobada

Vuelve a verificar el árbol de trabajo sucio, preserva los cambios no relacionados y realiza la implementación coherente más pequeña. Los comentarios deben explicar invariantes no obvias o decisiones de compatibilidad, no reafirmar el código.

No elimines datos de dominio subyacentes solo porque su presentación en la interfaz de usuario se haya eliminado, a menos que la eliminación haya sido aprobada explícitamente. Al cambiar estados persistentes, rutas, esquemas o enumeraciones, maneja los valores heredados cuando el repositorio indique que pueden existir.

7. Verifica e informa

Ejecuta primero pruebas enfocadas, luego verificaciones proporcionadas en todo el repositorio, como verificación de tipos, lint, pruebas completas, compilación y verificación visual o de interacción de la interfaz de usuario. No afirmes que una verificación pasó si no pudo ejecutarse.

Informa el resultado implementado, los archivos principales, la evidencia de verificación, las limitaciones conocidas y cualquier advertencia preexistente no relacionada. Si una superficie de validación solicitada no está disponible, divúlgala y no evites una herramienta o entorno seleccionado explícitamente sin aprobación.

Condiciones de parada obligatorias

Detente y solicita una decisión cuando:

• dos opciones factibles produzcan un comportamiento de usuario materialmente diferente;
• la implementación requiera una dependencia, integración, credencial, migración, acción destructiva o cambio de regla de negocio no aprobado;
• los cambios actuales del usuario se superpongan con la edición requerida y no se puedan preservar de manera segura;
• los hechos del repositorio contradigan la opción aprobada;
• los criterios de aceptación no se puedan hacer observables;
• completar el cambio de manera segura requiera expandir el alcance aprobado.

La dificultad, la duración o los detalles de implementación ordinarios no son razones para reabrir una decisión confirmada.

Estándar de finalización

El flujo de trabajo se completa solo cuando la opción seleccionada se implementa dentro del alcance, se manejan las decisiones de compatibilidad, los criterios de aceptación se asignan a evidencia observable, se han ejecutado las verificaciones relevantes y las limitaciones se informan honestamente.