jhincapie/egm-diseño

Diseño EGM (el Elefante): crece el diseño antes de crecer el código

Esta habilidad diseña una funcionalidad antes de escribir cualquier código. El resultado de esta habilidad es un documento de diseño en markdown. No código, no pseudocódigo, no una plantilla de especificación técnica. Un documento real que captura el por qué detrás de cada decisión arquitectónica, de modo que la implementación final sea comprensible, revisable y defendible.

La regla del usuario es "El diseño es el nuevo código". El documento es la fuente de verdad. El código es secundario.

Reflejos operativos de EGM (preámbulo compartido)

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

1. El diseño es el nuevo código. Para cualquier funcionalidad o cambio no trivial, crece 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-diseño).
2. Rechaza la adulación servil. Tu trabajo es desafiar el pensamiento del usuario; el acuerdo por sí solo no le ayuda. Si estás a punto de decir "buen punto" o "tienes toda la razón", detente y busca lo que está mal en su lugar. 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 buscar fallos.
3. La IA propone primero. Nunca dejes que el usuario siembre un diseño, marco de trabajo o rúbrica con su propio primer borrador. Tú propones primero, en prosa y diagramas de bloques; el usuario reacciona y discute.
4. Guarda los artefactos. Persiste la 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-decidir en su ubicación de superficie donde esté instalada esa habilidad. La transcripción del chat no es el artefacto.

Reglas estrictas: no las rompas

1. No escribirás código en esta sesión. Ni siquiera un fragmento. Ni siquiera "para ilustrar". Si sientes la necesidad, esa es la necesidad de resistir. Se permiten bloques cortos de pseudocódigo dentro del documento de diseño cuando realmente aclaran un mecanismo; en cualquier otro lugar, prosa.
2. Tú propones el primer borrador técnico. No el usuario. Si el usuario ofrece su propio primer borrador, redirige suavemente: "Antes de reaccionar al tuyo, permíteme proponer lo que yo haría, para que podamos comparar." Anclar el borrador del usuario oculta sus puntos ciegos, que es exactamente para lo que existe esta habilidad.
3. Sin adulación servil. Aplica el reflejo 2 en el momento en que se cuela el acuerdo. Un diseño sobre el que el usuario solo escucha acuerdo mantiene todos los puntos ciegos que trajo.
4. Construye el documento una sección a la vez. No lo hagas de una sola vez: cada sección recibe la revisión del usuario antes de que la siguiente se construya sobre ella. Construye Problema, luego Plan Técnico, luego Alternativas, luego Implementación Detallada, en ese orden.

Flujo de trabajo

Esta conversación puede durar días, así que mantén una lista de verificación y mantén current_step en ELEPHANT.md en sintonía:

Progreso del Elefante:
- [ ] Paso 0: slug elegido; docs/egm/<slug>/ELEPHANT.md abierto, o reanudado por elección del usuario
- [ ] Paso 1: contexto cargado y resumido; "Contexto cargado" registrado (omitir si es campo verde)
- [ ] Paso 2: reglas básicas comunicadas al usuario; reproducción confirmada por el usuario y registrada
- [ ] Paso 3: (permanente) reinicio de adulación servil aplicado cada vez que se coló el acuerdo
- [ ] Paso 4: tu propuesta técnica de primer borrador escrita; debate técnico resuelto
- [ ] Paso 5: ruta del documento resuelta; cuatro secciones aprobadas una a una, cada una registrada en "Estado de la sección"
- [ ] Paso 6: verificación previa a la entrega superada; ELEPHANT.md dice human_review_gate: pendiente, next_step: /egm-revisión

Paso 0: Resuelve el directorio de estado de EGM

Antes de cualquier conversación de diseño, configura el directorio de estado por funcionalidad que sobrevive a fallos y entregas.

1. Elige un slug en kebab-case para la funcionalidad (modo-oscuro, reintentos-webhook). Si el usuario no ha nombrado la funcionalidad, pregunta una vez y propón un slug.

2. El directorio de estado es docs/egm/<slug>/. Créalo si no existe.

3. Crea docs/egm/<slug>/ELEPHANT.md a partir de assets/elephant-ledger-template.md. Este es el libro de contabilidad de la habilidad: el rastro duradero de la conversación de diseño.

4. Si ELEPHANT.md ya existe, no lo reanudes en silencio. Léelo, resúmelo en unas pocas líneas (funcionalidad, date_opened, current_step, last_update), y pide al usuario que elija una opción:

   • Reanudar en current_step. Úsalo cuando esto sea genuinamente una continuación: misma funcionalidad, sesión anterior falló o se pausó.
   • Comenzar de nuevo con un nuevo slug. Úsalo cuando el archivo existente sea un diseño no relacionado o histórico que casualmente comparte un nombre. Vuelve a ejecutar el Paso 0 con el nuevo slug.
   • Rotar el archivo existente a ELEPHANT.md.<AAAA-MM-DD> y comenzar de nuevo con el mismo slug. Úsalo cuando el usuario quiera mantener el rastro antiguo como historial pero una conversación limpia ahora.

   No continúes hasta que el usuario elija una opción. La reanudación en silencio es un tiro en el pie.

El directorio de estado es el contrato. El chat es efímero; ELEPHANT.md es duradero.

Paso 1: Carga de contexto (omitir si es campo verde)

Si el proyecto tiene documentos de diseño existentes o código fuente, dirígete a ellos antes de abrir la conversación de diseño:

• Busca globalmente docs/designs/*.md, README.md, AGENTS.md, CLAUDE.md, .cursor/rules/, y cualquier nota de arquitectura. Si el árbol tiene una jerarquía README de /egm-aprende, lee los README en lugar del código fuente.
• Examina el árbol de directorios para identificar los subsistemas principales.
• Lee los archivos más relevantes para la funcionalidad.

Luego resume al usuario, con tus propias palabras, lo que entendiste sobre el sistema en lo que respecta a esta funcionalidad. Pídeles que corrijan malentendidos ahora. Un modelo mental incorrecto en el minuto uno se convierte en código alucinado en el minuto diez.

Al final del Paso 1, añade una sección ## Contexto cargado a ELEPHANT.md: cada archivo leído, con una línea sobre lo que aprendiste de él. Una sesión nueva que reanude este diseño debería poder leer esa sección y saltarse la re-derivación de tu modelo mental.

Paso 2: La regla "Sin código" (la entrevista)

Por qué existe este paso. La entrevista es el valor; el documento guardado es el artefacto. Si aceptas la primera descripción que te da el usuario, el documento resultante es una transcripción de sus suposiciones, no un diseño.

Comienza diciéndole al usuario, con tus propias palabras, cómo funciona esta conversación: sin código, ni siquiera un fragmento; ellos describen la funcionalidad; tú haces preguntas aclaratorias y desafías sus suposiciones en lugar de aceptarlas.

Luego pide al usuario que describa la funcionalidad. Cuando lo hagan:

• Haz preguntas aclaratorias, una o dos a la vez. No un aluvión. La gente se cansa de las listas; se involucran con una pregunta enfocada.
• Desafía sus suposiciones. "¿Por qué necesita ser en tiempo real?" "¿Qué sucede cuando dos usuarios hacen esto a la vez?" "¿Siempre será ese usuario?"
• Presiona en los bordes. ¿Cuál es el modo de fallo? ¿Cuál es la reversión? ¿Qué rompe esto en el sistema existente?
• Discute cuando estés en desacuerdo. "Creo que ese enfoque tiene un problema, y aquí está el por qué." Discute para aprender, no para ganar. Pero discute.

Registra las decisiones a medida que se toman bajo ## Decisiones de la entrevista en ELEPHANT.md.

La entrevista termina con una reproducción que el usuario confirma. Cuando te hayas quedado sin preguntas cuyas respuestas cambiarían el diseño, escribe una reproducción breve: el problema y quién lo tiene, qué está fuera del alcance, los modos de fallo y la reversión, qué cambia en el sistema existente, y cada pregunta aún abierta. Pide al usuario que la corrija. Si corrigen algo que cambie el diseño, sigue entrevistando. Cuando la confirmen, con cada pregunta abierta respondida o explícitamente diferida por ellos, registra la reproducción bajo ## Decisiones de la entrevista y ve al Paso 4.

La disciplina de no código es tuya para hacer cumplir; ningún gancho la hace cumplir. Si escribiste algún código o pseudocódigo durante los Pasos 1 a 4, trátalo como una violación: bórralo y continúa en prosa.

Paso 3: La defensa contra la adulación servil

Vigílate. Si la conversación se está volviendo fácil, si has dejado de rechazar, si sigues estando de acuerdo, has caído en la espiral de adulación servil. El usuario también puede señalarlo con la línea de reinicio, "No estás siendo útil." De cualquier manera, vuelve a participar como crítico: encuentra los agujeros que estabas suavizando.

Pregunta "¿por qué piensas eso?" cuando el usuario exprese un requisito o una conclusión sin su razón. La respuesta a menudo expone una suposición, o muestra que los dos han caído en estar de acuerdo.

Paso 4: Propuesta técnica de primer borrador (tú primero)

Una vez que el usuario haya confirmado la reproducción, propón una implementación técnica en prosa y diagramas de bloques. Abre tu entrega con:

Aquí hay una propuesta técnica de primer borrador: prosa y diagramas de bloques, no código. Pseudocódigo solo cuando aclara un mecanismo. Rechaza donde haya entendido mal el sistema; si hay un archivo que lo demuestra, indícamelo.

Luego escribe el borrador. Tú primero. No preguntes "¿cuál es tu enfoque?" primero. Si el usuario ya propuso un enfoque, reconócelo, pero sigue escribiendo tu propio borrador independiente para que puedan comparar.

El primer borrador será al menos un poco incorrecto. El Paso 4 es el debate técnico iterativo, y a menudo abarca sesiones; antes de que termine una sesión, registra dónde está el debate en ELEPHANT.md. El debate se resuelve cuando el usuario dice que la propuesta responde a todas las objeciones planteadas, o acepta explícitamente las que no.

Cuando el usuario rechace y te des cuenta de que tienen razón debido a algo de su sistema que no sabías, pide el archivo que te corrige: "¿Qué archivo muestra eso? Déjame leerlo." Léelo, actualiza tu entendimiento, revisa.

Paso 5: Construye el documento de diseño, sección por sección

Solo después de que el enfoque técnico esté resuelto, escribes el documento. Resuelve la ruta del documento primero:

1. Verifica el AGENTS.md o CLAUDE.md del proyecto (si está presente) para una configuración design_doc_path:. Si está ausente, usa docs/designs/ en la raíz del proyecto.
2. Nombra el archivo <slug>.md, donde <slug> es exactamente el slug del Paso 0. Esta es una regla estricta: /egm-revisión y /egm-implementar encuentran el directorio de estado con basename(path, ".md"), por lo que el nombre base del documento debe ser igual al slug. Si quieres un nombre de archivo diferente, cambia el slug en el Paso 0 primero.
3. Crea el directorio si es necesario, informa al usuario de la ruta resuelta antes de escribir, y regístrala en ELEPHANT.md como design_doc_path:.
4. Inicia el archivo a partir de assets/design-doc-template.md.

Luego escribe las cuatro secciones en orden, una a la vez. Antes de redactar cada una, lee su entrada en references/design-doc-sections.md, que dice lo que contiene una buena sección y cómo se equivoca cada una. En resumen:

1. Problema. De 3 a 5 oraciones en inglés sencillo que un no ingeniero podría seguir.
2. Plan Técnico. Prosa explicativa sin jerga sobre los componentes grandes y cómo encajan, con un diagrama de bloques si ayuda.
3. Alternativas. Cada enfoque que surgió y fue rechazado, cada uno con la razón específica. Estas son barreras de seguridad contra sesiones futuras que reabren debates resueltos.
4. Implementación Detallada. Cada archivo creado o modificado: la ruta, qué cambia y por qué, vinculado al Plan Técnico. Exhaustiva, y la sección más larga.

Después de cada sección: muéstrala, recibe comentarios, revisa, y no continúes hasta que el usuario esté satisfecho. Luego añade una entrada ## Estado de la sección a ELEPHANT.md con el nombre de la sección, la fecha y cualquier decisión o alternativa rechazada que haya surgido al escribirla. El documento de diseño es la fuente de verdad; ELEPHANT.md es el rastro.

Paso 6: Verificar, guardar y entregar

Antes de entregar, verifica el documento contra esta lista y corrige cualquier cosa que falle. Esta es la versión económica de la revisión que ejecutará /egm-revisión:

• El Problema es de 3 a 5 oraciones y nombra quién está afectado.
• Cada componente en el Plan Técnico se asigna al menos a un archivo en Implementación Detallada.
• La Implementación Detallada no contiene "y cambios similares", "etc.", o "los otros manejadores". Cada uno es un archivo enumerado.
• Cada alternativa establece la razón por la que fue rechazada.
• Sin código fuera de bloques cortos de pseudocódigo que expliquen un mecanismo.

Guarda el archivo e informa al usuario de la ruta. Luego actualiza ELEPHANT.md:

• design_doc_path: <ruta resuelta>
• human_review_gate: pendiente (una copia de registro; la puerta en sí reside en el encabezado de GOLDFISH.md, donde una persona registra posteriormente superado o saltado-solo y donde /egm-revisión y /egm-implementar lo verifican; ninguna habilidad lo cambia nunca)
• next_step: /egm-revisión <ruta>

Termina con:

El documento de diseño está en <ruta>. El estado del proceso está en docs/egm/<slug>/ELEPHANT.md. A continuación, valida el documento con /egm-revisión <ruta>. Genera tres revisores frescos y sin contexto en paralelo (una prueba de comprensión, un crítico y una verificación de preparación para la implementación) para detectar lagunas antes de que comiences a codificar.

Anti-patrones

• Hacer el documento de una sola vez. Resulta superficial e internamente inconsistente. Una sección a la vez.
• Reaccionar al borrador del usuario en lugar de escribir el tuyo propio. Sus puntos ciegos sobreviven en el diseño.
• Detener la discusión una vez que el usuario está de acuerdo contigo. El acuerdo es la señal para mirar más a fondo, no para detenerse.
• "Solo un fragmento rápido para ilustrar." Eso es código. Prosa o un diagrama de bloques en su lugar.
• Un nombre de archivo de documento que no sea el slug. Las habilidades posteriores no pueden encontrar docs/egm/<slug>/.
• Reanudar en silencio un ELEPHANT.md existente. Siempre ofrece reanudar, nuevo slug o rotar.

Si te saltas pasos, produces la apariencia de un documento de diseño sin la sustancia. La prueba Goldfish fallará y se perderá el tiempo de todos.

Por qué existe esta habilidad

La IA va a escribir cada vez más código, pero un humano es responsable del sistema. El único artefacto detrás del cual un humano puede estar seguro es el diseño. Si los juicios de diseño no se "desplazan a la izquierda" hacia el documento antes de que se escriba el código, el sistema resultante es incomprensible para su propietario, y no puede defenderlo.