Revisión Codex — Diff rama actual vs develop

Primera línea del informe generado: "Español confirmado."

Fast path (resumen ejecutable)

1. Leer references/metodologia-codex-completa.md   (~70 líneas, completo)
2. Leer references/plantillas-hallazgos.md          (~230 líneas, completo)
3. cd a drupal/ si existe, si no raíz del workspace
4. git rev-parse --abbrev-ref HEAD                  → guardar como <rama>
5. git fetch origin develop                         (silencioso)
6. git diff --name-only origin/develop...HEAD       → lista de archivos
7. Aplicar Decision tree para elegir puntos Codex prioritarios
8. Aplicar las 5 preguntas del framework Codex (sección siguiente)
9. Revisar archivo por archivo, anotando hallazgos con Severidad
10. Detectar IDE: leer CLAUDE_CODE_ENTRYPOINT (claude-vscode/claude-cursor/claude-antigravity).
    Solo si no es concluyente, caer a detección por carpeta existente.
11. Escribir informe en <carpeta-IDE>/Revisiones diff/lint-review-diff-develop-<rama>.md
11. Auto-verificar contra el Checklist de auto-verificación (final del documento)

Si cualquier paso falla, detente y consulta la sección "Edge cases del propio flujo".

Antes de revisar — pregúntate (framework Codex)

1. ¿Qué tipo de cambio es? Hook nuevo, refactor, hotfix, migración, config — el tipo determina qué puntos Codex aplican.
2. ¿Cuál es el peor escenario en producción? Si este código falla, ¿qué se rompe? Eso fija la severidad de los hallazgos.
3. ¿Hay algo fuera del diff que el cambio asume? Schema, config, dependencias, índices BD, permisos — los olvidos viven en lo que no se ve.
4. ¿Es idempotente? Si se ejecuta dos veces (retry, doble clic, re-deploy, re-import config), ¿pasa algo malo?
5. ¿Se puede desactivar? ¿Hay kill-switch (config/setting/feature flag) si la feature explota a las 3am sin tiempo de redeploy?

Si no puedes responder a las cinco con confianza, lee el código circundante antes de emitir el informe.

Ejemplo de aplicación (mini-diff)

Diff: añade

mymodule_node_update()

db_query("INSERT ... VALUES ('" . $title . "')")

• (1) Tipo: hook de entidad + escritura SQL → aplican Codex 1, 3, 4, 9.
• (2) Peor escenario: SQL injection si

  $title

  viene de input + nodos nuevos sin score (falta

  _insert

  ).
• (3) Asume: que la tabla custom existe (¿hay update hook? ¿schema?).
• (4) Idempotente: ¿qué pasa al re-guardar el nodo? ¿duplica filas o hace UPDATE? Verificar.
• (5) Kill-switch: no hay → hallazgo Media (Codex 11).

Resultado: 4 hallazgos (3 Alta + 1 Media), ninguno fuera del alcance del diff.

Ubicación fija (no preguntar)

• Repo git: si existe carpeta

  drupal/

  en el workspace, los

  git

  se ejecutan dentro de

  drupal/

  . Si no, raíz del workspace.

• Carpeta de salida (auto-detectada por IDE):

  Paso 1 — detectar el IDE por variable de entorno (PRIORITARIO). Ejecuta

  printenv CLAUDE_CODE_ENTRYPOINT

  (o equivalente) y aplica:

  CLAUDE_CODE_ENTRYPOINT	Carpeta a usar
  claude-antigravity	.antigravity/Revisiones diff/
  claude-cursor	.cursor/Revisiones diff/
  claude-vscode	.vscode/Revisiones diff/
  otros ( cli , vacío, etc.)	continuar al Paso 2

  Señales secundarias si

  CLAUDE_CODE_ENTRYPOINT

  no es concluyente:

  __CFBundleIdentifier

  (

  com.microsoft.VSCode

  → VS Code,

  com.todesktop.*

  → Cursor,

  com.google.Antigravity

  → Antigravity), o

  VSCODE_PID

  /

  CURSOR_*

  /

  ANTIGRAVITY_*

  cuando existan.

  Si el IDE se identificó por env, crea la carpeta correspondiente aunque no exista todavía. NUNCA caigas a detección por carpeta cuando el env var es claro — eso causa el bug de elegir

  .cursor/

  solo porque sobrevive de un uso anterior del IDE.

  Paso 2 — fallback por existencia de carpeta (solo si no hay señal de env):

  1. Si existe

     .antigravity/

     en la raíz del workspace →

     .antigravity/Revisiones diff/

  2. Si existe

     .cursor/

     (y no

     .antigravity/

     ) →

     .cursor/Revisiones diff/

  3. Si existe

     .vscode/

     (y no las anteriores) →

     .vscode/Revisiones diff/

  4. Si no existe ninguna →

     docs/revisiones-diff/

• Nombre del archivo:

  lint-review-diff-develop-<rama>.md

  . Crear la carpeta si no existe. Un archivo por rama (no sobrescribir entre ramas).

Flujo

1. Detectar contexto del diff:

   • git rev-parse --abbrev-ref HEAD

     → rama actual.

   • git fetch origin develop

     (silencioso, ignorar fallo de red).

   • git diff --name-only origin/develop...HEAD

     → lista de archivos.
   • Aplicar el Decision tree (siguiente sección).
2. Cargar referencias necesarias (ver sección "Carga de referencias").
3. Revisar solo los archivos del diff + dependencias mínimas.
4. Emitir el informe con la estructura obligatoria.

Decision tree según contenido del diff

.module

.php

.twig

.yml

*.schema.yml

*.routing.yml

*.services.yml

*.install

migrate_plus.migration.*

.scss

.js

origin/develop

composer.lock

Carga de referencias

Esta skill tiene dos archivos en

references/

• MANDATORY — leer ANTES de citar puntos Codex: lee completo

  references/metodologia-codex-completa.md

  (~70 líneas, 18 puntos con el PORQUÉ). NUNCA parafrasees los puntos sin haberlo leído. NUNCA uses range limits al leerlo.
• MANDATORY — leer ANTES de redactar hallazgos: lee completo

  references/plantillas-hallazgos.md

  (~230 líneas, 14 plantillas con código real). Adapta los snippets al diff real, no inventes código.
• Si ya las has leído en esta sesión, no recargar — el contexto las conserva.
• Do NOT load ninguna otra documentación externa, README, ni archivos del propio módulo más allá del diff y dependencias mínimas.

NEVER (lecciones aprendidas a las malas)

• NUNCA marcar "Alta" un hallazgo de estilo (typo, espacio, comentario). Por qué: diluye severidad, el equipo deja de leer las Altas reales.
• NUNCA sugerir refactors fuera del diff salvo seguridad crítica o data loss. Por qué: rompe el alcance del PR y genera fricción con el autor.
• NUNCA aprobar

  \Drupal::service()

  en clases nuevas con el argumento "ya había antes". Por qué: perpetúa deuda y bloquea testing.
• NUNCA dar por bueno

  accessCheck(FALSE)

  sin comentario

  // accessCheck OK porque...

  en la línea siguiente. Por qué: bypass silencioso de permisos.
• NUNCA aprobar migración sin verificar

  id_map

  y

  file_usage

  (si maneja media). Por qué: rollbacks rotos.
• NUNCA aprobar

  |raw

  en Twig sin verificar que el origen es 100% controlado por el sistema. Por qué: XSS persistente.
• NUNCA aprobar

  $query->execute()

  dentro de

  hook_*_alter

  sin cache. Por qué: N+1 en cada render.
• NUNCA aprobar nuevo

  dependencies:

  en

  *.info.yml

  sin verificar que el módulo está en

  composer.json

  . Por qué: deploy roto en CI.
• NUNCA escribir el informe en inglés. Código y comandos en inglés; explicaciones en español.
• NUNCA marcar el informe como "OK" si hay cualquier hallazgo de severidad Alta sin resolver.
• NUNCA citar un punto Codex sin haber leído

  references/metodologia-codex-completa.md

  en esta sesión.
• NUNCA aprobar

  EntityFieldManagerInterface::getFieldStorageDefinitions()

  sin verificar que el field exists primero. Por qué: tras eliminar un field y antes de

  cron

  /

  field_purge_batch

  , el storage queda zombi y revienta queries.
• NUNCA aprobar Batch API nueva sin

  finished

  callback que maneje

  $success === FALSE

  . Por qué: batches que fallan en mitad dejan datos a medias y nadie se entera.
• NUNCA aprobar

  entityTypeManager->getStorage()->loadMultiple()

  sin

  array

  vacío como guarda. Por qué:

  loadMultiple([])

  devuelve TODAS las entidades — bug clásico de fuga de memoria.

Severidades (criterio fijo)

Si dudas entre dos niveles, baja uno. Las Altas deben ser realmente Altas.

Estructura obligatoria del informe

Español confirmado.

# Revisión de código — Diff develop (rama actual: <rama>)

## Resumen ejecutivo
<2-4 frases: alcance del diff, conteo por severidad, veredicto>

## Hallazgos por categoría
### Seguridad
### Lógica de negocio / Codex
### Estándares / DI
### Performance / Cache
### Accesibilidad / i18n
### Tests / CI

## Riesgos (tabla)
| Área | Riesgo | Severidad | Mitigación |

## Sugerencias accionables
1. ...

## Checklist final
- [ ] Hallazgos Alta resueltos
- [ ] Tests pasan
- [ ] Schema config actualizado
- [ ] Update hooks idempotentes

Cada hallazgo va con Problema (Severidad), Riesgo y Solución (con código). Adapta las plantillas de

references/plantillas-hallazgos.md

Idioma y tono

• Español en todo el texto. Inglés en código, nombres de clase, comandos y rutas.
• Tono profesional, directo, simpático con el equipo que aplicará las correcciones.
• Detalle proporcional a la complejidad del hallazgo.

Checklist de auto-verificación (antes de entregar)

Antes de dar por cerrado el informe, comprueba uno por uno:

• Primera línea del informe es exactamente

  Español confirmado.

• El archivo está en

  .cursor/Revisiones diff/lint-review-diff-develop-<rama>.md

• He leído

  references/metodologia-codex-completa.md

  en esta sesión
• He leído

  references/plantillas-hallazgos.md

  en esta sesión
• Cada hallazgo tiene Problema (Severidad), Riesgo y Solución
• Ninguna severidad "Alta" es solo de estilo (typo, espacio, comentario)
• Todas las soluciones de código compilan mentalmente y siguen DI/PSR-12
• No he propuesto cambios fuera del alcance del diff (salvo seguridad crítica)
• Todas las explicaciones en español, todo el código en inglés
• He aplicado las 5 preguntas Codex a cada bloque significativo
• El informe incluye Resumen ejecutivo, Hallazgos, Riesgos, Sugerencias y Checklist final
• Si hay hallazgos Alta sin resolver, el veredicto NO es "OK"

Si alguna casilla queda sin marcar, vuelve atrás y arregla antes de entregar.

Recovery — qué hacer si algo falla

references/metodologia-codex-completa.md

references/plantillas-hallazgos.md

git fetch

develop

.cursor/

develop