# Revisión de código

Lee un cambio contra lo que debía hacer y reporta qué se rompe, dónde y con qué entrada — antes de que llegue a alguien que no lo pidió.

## Entregable

Un documento Markdown, `code-review-report.md`, con la estructura fijada en **Salida** más abajo. Toma un cambio producido bajo **Planificación de implementación** y devuelve hallazgos sobre los que su autor puede actuar directamente.

## Entradas obligatorias

- **El cambio en sí** — un diff, un conjunto de archivos modificados o una comparación entre dos revisiones del sistema de control de versiones.
- **La intención del cambio** — qué debe hacer, en palabras de su autor o desde la especificación que implementa.

Si falta cualquiera de las dos, detente y repórtalo. Una revisión sin intención declarada encuentra estilo; no puede encontrar un cambio que hace correctamente lo que no tocaba.

## Entradas opcionales

- El código de alrededor al que el cambio llama y desde el que se le llama
- El conjunto de pruebas, y si pasa sobre el cambio
- Las entradas que el sistema acepta y los estados en los que puede estar
- Las convenciones de manejo de errores y de registro que sigue el proyecto
- Requisitos de seguridad, privacidad o cumplimiento aplicables a esta área
- Revisiones anteriores de la misma área, y qué pidieron

Las entradas opcionales ausentes limitan el alcance de la revisión, y cada hallazgo se acota en consecuencia: un hallazgo sobre comportamiento que no se pudo leer es una pregunta, no un defecto.

## Ejecución

**1 — Establecer qué debe hacer el cambio.** Reformula la intención en una frase y lista los comportamientos que implica. Todos entran en la lista, incluidos los caminos de error y el caso vacío. Esa lista es contra lo que se mide el diff.

**2 — Leer el cambio en orden de ejecución, no de archivo.** Sigue el camino que recorre de verdad una petición o una llamada por el código modificado. Leer en orden alfabético esconde la interacción entre dos archivos que solo falla cuando se ejecutan los dos.

**3 — Buscar corrección antes que nada.** Valores nulos y vacíos, límites, orden, acceso concurrente, fallo parcial, liberación de recursos y cada entrada que el código no valida. Por cada uno, nombra la entrada o el estado que lo dispara.

**4 — Probar cada hallazgo contra el código.** Un hallazgo debe nombrar el archivo, la línea y la entrada o el estado con los que falla. Si el fallo no se puede demostrar desde el código que se leyó, el hallazgo se registra como pregunta en la revisión, no se afirma como defecto.

**5 — Contrastar el cambio con la lista de comportamientos.** Todo lo del paso 1 que el diff no implementa es un hueco, y se reporta como tal y no como una opinión sobre lo que estaría bien.

**6 — Comprobar lo que no está.** Pruebas que faltan para los caminos modificados, ramas de error sin tratar, estados que el cambio introduce y no limpia, y llamadores que no se actualizaron.

**7 — Ordenar por severidad y escribir el arreglo.** Cada hallazgo recibe una severidad y el cambio que lo resuelve. Un hallazgo sin arreglo propuesto está incompleto, salvo que el arreglo sea una decisión que debe tomar su autor — en cuyo caso se nombra la decisión.

## Salida

`code-review-report.md`, en este orden:

- **1. Entrada y alcance** — qué se revisó, qué revisiones, qué no se leyó, y cuándo
- **2. Intención declarada** — la intención y los comportamientos que implica
- **3. Hallazgos** — ordenados por severidad; por hallazgo: severidad, archivo, línea, qué se rompe, la entrada o el estado que lo dispara, y el arreglo
- **4. Preguntas** — problemas sospechados que no se pudieron demostrar, cada uno con lo que lo resolvería
- **5. Huecos frente a la intención** — comportamientos que la intención implica y el cambio no implementa
- **6. Cobertura que falta** — caminos modificados sin prueba, y ramas de error sin tratar
- **7. Lo que no se revisó** — archivos, caminos o comportamiento fuera del material aportado

## Validación

El informe está listo cuando se cumple todo esto:

- Cada hallazgo de la sección 3 nombra un archivo, una línea y la entrada o el estado que dispara el fallo
- Ningún hallazgo de la sección 3 carece de fallo demostrado; los no demostrados están en la sección 4
- Cada comportamiento de la sección 2 aparece como implementado, como hallazgo o en la sección 5
- Cada hallazgo lleva una severidad y un arreglo, o la decisión que necesita
- La sección 6 lista los caminos modificados sin prueba, o declara que todos están cubiertos
- La sección 7 nombra lo que el material aportado no permitió comprobar

Falla la ejecución si se afirma un hallazgo sin archivo y línea, o si los comentarios de estilo van por delante de los hallazgos de corrección.

## Gestión de fallos

- **Sin intención aportada** — detente. Informa de que el cambio no se puede revisar contra su propósito, y de que revisar código contra sí mismo solo detecta incoherencias internas.
- **Una descripción en lugar de un diff** — detente. Informa de que la descripción de un cambio no es un cambio, y nombra lo que hace falta.
- **Sin acceso al código de alrededor** — revisa solo el diff, lleva a la sección 4 como pregunta todo hallazgo que dependa de un llamador, y declara con claridad qué no se pudo leer.
- **La intención y el código no coinciden** — repórtalo como hallazgo con la severidad más alta que el desacuerdo pueda causar, y nombra ambas fuentes. No decidas cuál tiene razón.
- **Un cambio muy grande** — revísalo en el orden del paso 2, entrega lo cubierto y nombra el resto en la sección 7. Una revisión parcial que declara su límite es utilizable; una que insinúa que está completa, no.