jhincapie/egm-drift-report

EGM Drift Report: lo que el diseño decía versus lo que se construyó

/egm-implement construye a partir del documento de diseño y registra la deriva en IMPLEMENT.md a medida que ocurre. Sin embargo, algo de deriva se escapa: un cambio que la sesión consideró demasiado pequeño para registrar, una corrección posterior, una interfaz que se asentó de manera diferente una vez que existieron llamadores reales. Esta skill mide la brecha después del hecho y la documenta, para que el usuario pueda luego decir "actualiza el diseño para que coincida" y el diseño vuelva a ser la fuente de verdad.

Invoca como /egm-drift-report [ruta-al-documento-de-diseño].

Reflejos operativos de EGM (preámbulo compartido)

Cada skill de este conjunto incorpora estos cuatro reflejos, porque no todas las superficies cargan un CLAUDE.md global. Provienen del artículo Elephant-Goldfish y aplican para toda la sesión, no solo mientras esta skill se ejecuta.

1. El diseño es el nuevo código. Para cualquier característica o cambio no trivial, desarrolla un documento de diseño antes de escribir código. Si el diseño no es lo suficientemente claro como para que el código se escriba solo, diseña primero (/egm-design).
2. Rechaza la adulación. Tu trabajo es desafiar el pensamiento del usuario; estar de acuerdo por sí solo no lo ayuda. Si estás a punto de decir "buen punto" o "tienes toda la razón", detente y busca qué está mal. Si el usuario dice "No estás siendo útil" (el reinicio de EGM), trátalo como una señal de que has estado demasiado de acuerdo y vuelve a encontrar fallos.
3. IA propone primero. Nunca permitas que el usuario siembre un diseño, marco o rúbrica con su propio borrador inicial. Propón tú primero, en prosa y diagramas de bloques; el usuario reacciona y discute.
4. Guarda los artefactos. Persiste el triplete descripción + criterios + salida de forma duradera: docs/designs/<slug>.md, los libros de contabilidad en docs/egm/<slug>/, PEANUTS.md en la raíz del código fuente, y el triplete de /egm-decide en su ubicación mapeada en la superficie donde esa skill está instalada. La transcripción del chat no es el artefacto.

Reglas estrictas: no las rompas

1. Solo lectura. El único archivo que esta skill escribe es docs/egm/<slug>/DRIFT-REPORT.md. Nunca edites el documento de diseño, el código, las pruebas ni ningún otro libro de contabilidad (IMPLEMENT.md, GOLDFISH.md, ELEPHANT.md). Aplicar las actualizaciones sugeridas es una solicitud separada que el usuario hace después.
2. Evidencia o no es deriva. Cada elemento cita lo que dice el diseño (sección y una cita corta) y lo que se construyó (ruta:línea, o un commit, o "no existe tal archivo"). Un elemento sin evidencia en ambos lados es una pregunta abierta, listada como tal.
3. El código es el hecho observado; el diseño es la afirmación. Reporta la diferencia de manera neutral. No decidas cuál es correcto a menos que un libro de contabilidad registre la decisión; la actualización sugerida es una propuesta, no un veredicto.
4. Ojos frescos hacen la comparación. La sesión que implementó la característica está sesgada a leer su propia intención en el código. Entrega la comparación a un subagente de solo lectura nuevo (Paso 3) siempre que haya uno disponible.

Flujo de trabajo

Progreso del informe de deriva EGM:
- [ ] Paso 1: documento de diseño y slug resueltos; docs/egm/<slug>/ encontrado
- [ ] Paso 2: commit base elegido; lista de rutas del paquete de evidencia
- [ ] Paso 3: comparación ejecutada por un subagente de solo lectura nuevo (o en línea, anotado)
- [ ] Paso 4: hallazgos verificados, clasificados y escritos en DRIFT-REPORT.md
- [ ] Paso 5: usuario informado de dónde está el informe y que puede solicitar aplicar las actualizaciones

Paso 1: Resolver el documento de diseño

Prefiere el argumento del usuario. De lo contrario, busca en la carpeta nombrada por design_doc_path: en el archivo AGENTS.md o CLAUDE.md del proyecto, y si no, en docs/designs/*.md. Si existe exactamente un documento, úsalo; si hay varios, enuméralos y pregunta cuál. El slug es el nombre del archivo del documento sin .md, y el directorio de estado es docs/egm/<slug>/. Si ese directorio no existe, la característica nunca pasó por /egm-design; dímelo y ofrece escribir el informe allí de todos modos (creando solo docs/egm/<slug>/DRIFT-REPORT.md).

Paso 2: Elegir la base y recopilar el paquete de evidencia

La base es el punto donde se aprobó el diseño. Elige la primera opción que aplique y registra cuál usaste:

1. El commit que estableció human_review_gate: passed (o skipped-solo) en docs/egm/<slug>/GOLDFISH.md: git log --format='%H %ad %s' --date=short -- docs/egm/<slug>/GOLDFISH.md.
2. El último commit que toca el documento de diseño en o antes de start_date en IMPLEMENT.md: git log --format='%H %ad %s' --date=short -- <doc>.
3. Pregunta al usuario por un commit o fecha.

Luego enumera, sin resumir, la evidencia que la comparación leerá:

• el documento de diseño (en HEAD, y en la base si cambió desde entonces: git show <base>:<doc>);
• docs/egm/<slug>/IMPLEMENT.md, especialmente ## Files touched, cada entrada ## Drift (abierta y resuelta) y ## Verification;
• notas de disposición de GOLDFISH.md donde registran un cambio en el documento;
• git log --stat <base>..HEAD y git diff --stat <base>..HEAD, más cambios no confirmados de git status y git diff;
• los archivos que enumera la Implementación Detallada del documento, y los archivos que el diff tocó y que el documento no menciona.

No están en el paquete: este chat, el razonamiento de diseño de ELEPHANT.md, ni tu propio recuerdo de por qué se hizo algo. Esos pertenecen a la columna "razón probable" solo cuando un libro de contabilidad lo dice.

Paso 3: Ejecutar la comparación en una sesión de solo lectura nueva

En Cursor, genera un subagente Task de tipo drift-auditor (instalado en ~/.cursor/agents/drift-auditor.md, readonly: true). Si no está instalado, usa un subagente Task genérico e indícale que es de solo lectura. Envía el prompt en assets/drift-auditor-prompt.md con la ruta del documento, slug, base y lista de evidencia completados. No agregues nada más: ningún resumen de la implementación, ninguna explicación de por qué cambiaron las cosas.

Si no existe un entorno de subagente, haz la comparación en línea siguiendo el mismo prompt tú mismo y registra comparison: inline (no fresh subagent available) en el encabezado del informe para que el lector sepa que no fue independiente.

Paso 4: Verificar, clasificar y escribir el informe

Verifica cada elemento devuelto antes de escribirlo: abre la ruta:línea citada y la sección del documento citada, y elimina o corrige cualquier cosa que la evidencia no respalde. Usa las categorías de la plantilla: changed-approach, added, not-built, renamed-or-moved, interface-change, data-model-change, behavior-change, new-dependency, constraint-discovered, alternative-switched. La gravedad es major (el documento engañaría a un lector sobre cómo funciona el sistema), minor (un detalle es incorrecto) o cosmetic (nombre, redacción).

Cruza referencia con IMPLEMENT.md: marca cada elemento como logged (existe una entrada de deriva, con su estado) o unlogged. Los elementos no registrados de gravedad major son los titulares.

Escribe docs/egm/<slug>/DRIFT-REPORT.md a partir de assets/drift-report-template.md. Si el archivo ya existe, coloca el nuevo informe con fecha en la parte superior debajo del encabezado del archivo y mueve los informes anteriores debajo de ## Earlier reports sin cambios. Nunca reescribas un informe anterior.

Si no hay deriva, escribe el informe de todos modos con drift_items: 0, la base utilizada y lo que se comparó, de modo que "sin deriva" sea un resultado registrado y no una ausencia.

Paso 5: Devolver al usuario

Informa al usuario, en esta forma:

Informe de deriva escrito en docs/egm/<slug>/DRIFT-REPORT.md: elementos ( graves, no registrados en IMPLEMENT.md). No he cambiado el documento de diseño ni el código. Cuando quieras que el diseño coincida con lo construido, pídeme que aplique las actualizaciones sugeridas del informe; los elementos que cambien el Plan Técnico deben pasar por /egm-design nuevamente, y una reescritura grande por /egm-review.

No apliques las actualizaciones en esta sesión a menos que el usuario lo solicite después de ver el informe.

Anti-patrones

• Corregir el diseño mientras se informa. El informe es el entregable. Editar el diseño mezcla la medición con el cambio y oculta cuál fue la deriva.
• Corregir el código para que coincida con el diseño. El mismo problema en la dirección opuesta. El usuario decide qué lado se mueve.
• Explicar la deriva de memoria. "Cambiamos esto porque X" sin una línea de libro de contabilidad es una suposición; escribe reason: unknown y deja que el usuario lo complete.
• Resumir el diff en lugar de comparar. Una lista de archivos cambiados no es un informe de deriva. Cada elemento vincula una afirmación del diseño con un hecho observado.
• Saltarse la sesión nueva para ahorrar tiempo. La sesión que implementó ya cree que el código coincide con el diseño. Esa creencia es lo que esta skill existe para probar.

Dónde se sitúa esta skill en EGM

/egm-learn (solo código heredado) → /egm-design → /egm-review → /egm-implement → /egm-code-review, con /egm-drift-report en cualquier momento después de /egm-implement (antes o después de la revisión de código).

• Lee: el documento de diseño, IMPLEMENT.md, GOLDFISH.md, el historial de git desde la base y el código.
• Escribe: solo docs/egm/<slug>/DRIFT-REPORT.md.
• Alimenta: una solicitud posterior de "actualizar el documento de diseño a partir del informe de deriva"; /egm-design para cambios en el Plan Técnico; /egm-review cuando el documento actualizado necesite revalidación.