johanhaleby/domain-storytelling

Domain Storytelling

Una historia de dominio es una imagen de un proceso de negocio contada como oraciones: un actor hace algo con un objeto de trabajo, a veces involucrando a otro actor. Los números en las flechas indican el orden. Nada más lo hace.

Este skill modela la historia y luego la renderiza. Lee references/notation.md y references/spec.md en una sola llamada antes de modelar algo no trivial. El archivo de especificación enumera cada nombre de icono.

Pasos

1. Modelar la historia. El borrador es el predeterminado: modela el caso típico a partir de lo que describió el usuario, elige iconos, renderiza y di qué suposiciones hiciste. Pregunta solo cuando una elección cambiaría el modelo en lugar de decorarlo.
2. Leer las oraciones una vez y preguntar cuál de ellas es opcional, o sucede de manera diferente algunas veces. Esas se convierten en anotaciones. Este es el paso más fácil de omitir, y omitirlo cuesta mucho, porque la notación no tiene ramas. Un paso que solo a veces sucede lleva una anotación o se une silenciosamente al camino feliz.
3. Ejecutar un taller en su lugar cuando el usuario lo solicite (/domain-storytelling workshop, "dirige un taller", "entrevístame sobre esto") o cuando un plan depende de un proceso que nadie ha documentado. Lee references/workshop.md ahora. Nunca entrevistes y dibujes al mismo tiempo.
4. Escribir la especificación y renderizarla como se indica en Renderizado más abajo.
5. Actuar sobre las advertencias. Cuando el generador escriba algo en stderr, lee references/warnings.md ahora. El generador termina con una línea que nombra ese archivo, por lo que una lectura omitida se muestra en la salida.
6. Inspeccionar la imagen leyendo la vista previa PNG que el render escribió, y nombra cada archivo escrito. Un renderizado está completo cuando no tiene advertencias y la imagen se traza limpiamente.

Reglas que no son negociables

Estas provienen del método, y romperlas produce algo que parece una historia de dominio pero no lo es.

• Cada actor aparece exactamente una vez. Una forma por actor, sin importar en cuántas oraciones aparezca.
• Dos personas en roles diferentes son dos actores, incluso cuando el dominio las llama igual. La regla anterior se refiere a un actor dibujado una vez, no a una palabra dibujada una vez. Antes de fusionar dos menciones del mismo sustantivo, pregúntate si una persona podría hacer ambos pasos. Cuando no podría, son actores separados, y obtienen formas y nombres separados que dicen qué rol juega cada uno aquí. Los números de secuencia son lo que hace que esto sea incorrecto en lugar de simplemente vago, porque afirman que el actor que realiza la oración 5 es el mismo que realizó la oración 2. Un solo Conductor que se une a la cola de una clasificación, libera un espacio de estacionamiento y luego reclama el espacio liberado dice que un conductor renunció a un lugar de estacionamiento y se le ofreció de vuelta, cuando el titular saliente y el que hace cola son dos roles que comparten un título de trabajo. Una anotación que nombre a otra persona que podría realizar el paso, "un administrador puede liberar el espacio de estacionamiento en su lugar", es la señal de que el actor del paso nunca se determinó.
• Cada actividad dibuja su propio objeto de trabajo. El mismo orden en tres oraciones son tres formas. Esto no es duplicación, es cómo la notación muestra que la cosa se mueve.
• Sin condicionales, ramas ni bucles. No hay puerta de enlace, ni diamante, ni "si" discontinuo. Modela una alternativa importante como una historia separada. Mantén una variación pequeña como anotación.
• Una oración comienza con un actor y el número de secuencia va en esa primera flecha. La flecha hacia un segundo actor lleva una preposición, no un número.
• Las oraciones que suceden al mismo tiempo comparten un número, y cualquier cantidad de ellas puede hacerlo. Repite el valor n entre ellas en la especificación. Esta es la única forma en que la notación dice "al mismo tiempo", ya que no tiene bifurcación ni unión, así que úsala siempre que ningún paso espere al otro. Mantén los números separados cuando uno realmente sigue al otro, porque un número compartido afirma más que "estos dos están relacionados".
• Usa las propias palabras del dominio. El verbo en la flecha es la palabra que el experto del dominio dijo. Si te encuentras escribiendo "procesa" o "maneja", no has entendido el paso todavía, así que pregunta. En una historia extraída del código, la palabra del dominio es el nombre de la acción que una persona desencadena, el botón, endpoint o comando, por lo que un endpoint cancel-reservation hace "cancela la reserva". Cada verbo nombra una acción, y dos acciones diferentes en una historia obtienen dos verbos diferentes. Sigue el endpoint hasta la pantalla que lo llama antes de nombrar al actor, y nombra al actor según los usuarios de esa pantalla, porque un usuario de backoffice y un servicio experto en el editor de administración son roles diferentes que pueden hacer cosas diferentes. Cuando una acción vecina tiene un efecto similar, cancelar la reserva de un lugar de estacionamiento frente a eliminar al que hace cola de la cola, la nota nombra la pantalla y el botón, y el vecino que no es.
• Un objeto de trabajo es un sustantivo que el dominio ya dice. "Factura", "Reclamo de lugar de estacionamiento". Un y en el nombre es la señal de que son dos, y la solución es elegir el que la actividad realmente mueve o escribir dos oraciones que compartan un número. La longitud es el síntoma más que la falla, por lo que acortar un nombre compuesto para que encaje solo lo oculta.
• Di el alcance en voz alta. Granularidad, punto en el tiempo, pureza del dominio. Una historia sin ellos es ambigua sobre lo que incluso afirma. Viaja en la especificación y en la descripción de Egon más que en la imagen, porque esos tres términos son el método hablando con el modelador y un lector de la imagen no puede decodificarlos.

Mostrar dónde aterriza un cambio

Cuando el punto de la historia es lo que un cambio hace a un proceso, marca las oraciones que toca con "changed": true y dílo en la descripción. Una imagen con el delta marcado generalmente supera a dos imágenes que el lector debe comparar visualmente. Dibuja una historia AS-IS y una TO-BE en su lugar cuando la forma del proceso cambió, es decir, pasos se movieron entre actores o desaparecieron, en lugar de cuando los pasos se quedaron igual y solo su contenido cambió.

Cuando el cambio decide quién obtiene algo, una oferta, una prioridad o un turno, dibuja el contraste: la persona que pierde y la persona que gana, como dos actores en el mismo rol nombrados por su posición ("Primero en la cola", "Segundo en la cola"). Termina en la oración que nombra cuál de ellos lo obtuvo. Con un actor en ese rol, una regla que pasa por alto a alguien se dibuja exactamente como una regla que no hace nada.

Una historia extraída del código en lugar de una persona es una lectura de ese código. Dílo al lado de la imagen, para que un lector sepa que no ha sido verificada con nadie que haga el trabajo. Antes de dibujar una oración cambiada, lee la guardia que decide cuándo se aplica el nuevo comportamiento: el estado que requiere y el evento que lo ejecuta. Dibuja ese evento como la oración anterior al cambio, y pon un estado que toda la historia mantiene, como "el conductor saliente todavía está estacionado allí", en la descripción. Una nota como "la próxima vez que se pregunte a la cola" no nombra a ningún actor, y es la señal de que el desencadenante nunca se encontró.

Cuántas historias

• Una historia por alternativa importante. Primero el camino feliz.
• AS-IS y TO-BE son siempre historias separadas, nunca una imagen.
• Una visión general amplia más una historia detallada para el paso que importa, cuando el proceso es grande.
• Divide en aproximadamente quince oraciones, sea lo que sea. Una imagen ancha y ocupada es el método diciéndote que la historia es demasiado grande.

Nombra un conjunto para que se lea como un conjunto: Reembolso - AS-IS, Reembolso - TO-BE.

Renderizado

Escribe una especificación como JSON, luego ejecuta el generador desde el directorio que contiene este SKILL.md:

python3 scripts/story2egn.py ruta/a/historia.json --preview <directorio temporal>

Solo biblioteca estándar. Escribe dos archivos junto a la especificación, o en --out-dir, y --preview agrega <Título>.png en un directorio propio, por lo que una llamada renderiza la historia y devuelve la imagen para leer. Apunta --preview a un directorio temporal o de trabajo, lejos de los archivos que se envían. El PNG proviene de rsvg-convert, cairosvg o inkscape cuando uno está instalado y de macOS Quick Look en caso contrario. --help lista los otros formatos y --date.

• <Título>.egn.svg es la imagen y el modelo editable en un solo archivo. Se abre en cualquier visor SVG y se importa en https://egon.io. Egon lee el título de la historia del nombre del archivo, por lo que el título en la especificación decide el nombre del archivo.
• <Título>.board.svg es la misma imagen para una página. Cada actor, objeto de trabajo, actividad y nota se encuentra en un grupo etiquetado con los pasos a los que pertenece, y lleva su propio modo oscuro. scripts/story-board.js puede atenuar, rodear o recortar a un paso. Un tablero dibujado a mano en egon.io no tiene etiquetas, por lo que permanece como una imagen plana.

Siempre dile al usuario las rutas que se escribieron. Muestra las imágenes en línea si el anfitrión puede mostrar imágenes, de lo contrario las rutas son el entregable. Nunca digas que se produjo una historia sin nombrar su archivo.

Leer una historia de vuelta

Los archivos .egn, .egn.svg y heredados .dst son leídos por el skill hermano egn-to-text. Úsalo en lugar de analizarlos aquí.