# Cambiar algo que ya funciona

> Cómo modificar una feature implementada con protocolo-cambios, su documento CHG y el alcance que el detector compara contra el commit.

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](https://ai-first.falcux.com/docs/guias/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:

```yaml
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:

   ```text
   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:

   ```md
   ### 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.

   ```text
   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](https://ai-first.falcux.com/docs/referencia/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](https://ai-first.falcux.com/docs/parte-3/protocolo-cambios/).

## Próximos pasos

[Cerrar la sesión](https://ai-first.falcux.com/docs/guias/cerrar-la-sesion/)El registro de sesión y la versión, después del cambio.

[Las cinco verificaciones](https://ai-first.falcux.com/docs/referencia/verificaciones/)Cómo lee el detector el alcance, con el resto de los checks.

[documento-de-cambio.md](https://raw.githubusercontent.com/HoruxDeEdfu/falcux-ai-first-package/prod/skills/protocolo-cambios/references/documento-de-cambio.md)El molde completo del CHG, tal como viaja con la skill.