Cambiar algo que ya funciona

Tienes algo que ya funciona y tiene que cambiar: un requerimiento que se movió, algo que la AI implementó mal, un patrón que no aguanta en mobile. Quieres cambiarlo sin que el agente lo reconstruya desde cero ni toque lo que no debe.

Cuándo usarla

• Un requerimiento cambia después de implementado.
• La AI implementó algo incorrecto y hay que corregirlo.
• Un patrón no funciona en la práctica y necesita ajustarse.
• Cambian prioridades que afectan features existentes.
• Cambia un documento de gobierno, como un artefacto que escribió el arranque.

No es para un typo o un botón roto, ni para un refactor que no cambia comportamiento. Una feature nueva que no toca nada existente es Desarrollar una feature.

Antes de empezar

protocolo-cambios viene en la instalación por defecto, con el molde del documento de cambio dentro, en su carpeta references/. init deja además la carpeta docs/changes/pending/, el registro docs/changes/CHANGE_LOG.md y, en AI-FIRST.md, la línea que hace que el detector lea el cambio en curso:

alcance:
  spec: docs/changes/pending/

Si tu AI-FIRST.md ya existía cuando corriste init, esa línea no se escribe: el reporte la deja como sugerida y hay que agregarla a mano.

Paso a paso

1. Clasifica el cambio. Hay cuatro tipos —corrección, ajuste de diseño, cambio de requerimiento, cambio de prioridad— y dos flujos:

   Flujo	Cuándo
   Corto	1–2 archivos, sin cambio de schema
   Completo	3 o más archivos, cambia el schema o cambian flujos de navegación

   Si el cambio toca una Zona Prohibida, se pide la aprobación antes de escribir el documento, no después.

2. Escribe el CHG antes de tocar código. Va en docs/changes/pending/CHG-XXX_nombre.md, con el número correlativo siguiente, copiado del molde de la skill:

   Usa protocolo-cambios. El listado de clientes pagina de a 20 y el equipo de
   ventas necesita filtrar por país. Clasifica el cambio, dime si es flujo corto
   o completo y escribe el CHG en docs/changes/pending/. No implementes nada.

   El corazón del documento es el par estado actual / estado deseado. Sin el estado actual descrito con precisión, la AI reconstruye el feature en vez de modificarlo. El flujo corto llena Metadata, §1 a §4, §9, §10, §13 y §14; el completo, todo.

3. Declara los archivos afectados entre acentos graves. Es lo que el detector compara contra lo que el commit tocó de verdad. El título de la subsección tiene que empezar por «Archivos» o «Alcance», sin número delante:

   ### Archivos afectados
   
   - [ ] `src/clientes/listado.ts` — agrega el filtro por país
   - [ ] `src/clientes/listado.test.ts` — casos del filtro
   - [ ] `src/clientes/componentes/**` — el selector nuevo

4. Analiza el impacto en una sesión aparte. En el flujo completo, una sesión dedicada que no modifica nada: archivos afectados directa e indirectamente, migraciones, tests que van a fallar, contradicciones con AGENTS.md o la spec, y lógica existente que cubra parte del cambio.

5. Implementa por pasos, en una sesión limpia. Nunca en la misma sesión donde se trabajó en otra cosa. Cada paso toca tres archivos o menos; si no, se subdivide.

   Vamos a implementar CHG-012 (docs/changes/pending/CHG-012_filtro-pais.md).
   Implementa SOLO el paso 1. Muéstrame el diff y no avances hasta que confirme.

   Para un cambio de requerimiento o de prioridad, la skill pide una rama propia: git checkout -b change/CHG-XXX-nombre.

6. Verifica. Contra el estado deseado del documento, los tests relevantes y, si el cambio tocó la interfaz, el skeleton: es la deriva que más se pierde en el flujo corto.

7. Cierra. Actualiza los docs afectados, agrega el resumen a docs/changes/CHANGE_LOG.md y elimina el archivo de pending/.

Nota

Un cambio que además es una decisión —difícil de revertir, con alternativas reales que se descartaron— lleva también su fila en docs/ADR.md, en el mismo commit que el CHG. No es duplicar: el CHG documenta qué cambió y se archiva; el ADR documenta por qué y sobrevive. La §6 del documento hace esa pregunta.

Qué queda escrito

Archivo	Cuándo
docs/changes/pending/CHG-XXX_nombre.md	Al abrir el cambio; se elimina al cerrarlo
docs/changes/CHANGE_LOG.md	Al cerrar: fecha, tipo, archivos, resumen y lecciones
docs/ADR.md	Si la §6 del documento dijo que sí
La spec del módulo, el PRD, la arquitectura, la guía de diseño	Los que el cambio afectó, al cerrar

Un archivo en pending/ sin actividad por dos semanas o más se revisa, y si ya no aplica pasa al registro como «Descartado».

Qué vigila el detector

Alcance excedido (P1) es el check de esta guía. Con alcance.spec apuntando a docs/changes/pending/, audit toma cada documento de esa carpeta, busca la sección cuyo título empieza por «Archivos» o «Alcance» y extrae las rutas entre acentos graves, con globs. Los archivos tocados que no coinciden con ninguna, por encima de la tolerancia, son un P1. La tolerancia es 0 si alcance.tolerancia no la declara.

• No cuentan como fuera de alcance AI-FIRST.md, la propia carpeta de cambios ni los artefactos declarados en AI-FIRST.md.
• Los placeholders con {llaves} y XXX del molde se ignoran.
• Sin ningún CHG abierto, el check se reporta omitido, no aprobado: no hay alcance que exceder. Con un CHG que no lista rutas, también se omite, y la razón lo dice.

Para evitar el hallazgo, declara los archivos en el CHG antes de implementar y, si el trabajo crece, actualiza la lista antes del commit. Si al cerrar no eliminas el documento de pending/, sigue contando como cambio abierto en la sesión siguiente.

Si el cambio suma una dependencia de producción o toca una superficie de decisión, también aplica Decisión sin fila en ADR (P1). El detalle de los cinco checks está en Las cinco verificaciones.

Por qué funciona así

Un cambio sin evaluación de impacto es una apuesta: el documento existe para que el humano entienda qué se toca y qué se puede romper antes de que la AI ejecute. El criterio completo está en el Protocolo de gestión de cambios.

Próximos pasos

Cerrar la sesiónEl registro de sesión y la versión, después del cambio.

Las cinco verificacionesCómo lee el detector el alcance, con el resto de los checks.

documento-de-cambio.mdEl molde completo del CHG, tal como viaja con la skill.