Project Management con Spec Driven DevelopmentBeta

0%
Bloque Ejecutivo

Módulo 15

Diagramas de Flujo y Alcance Visual

3.5h

Flowchart, State Machine y Sequence Diagrams con Mermaid. Comunicación visual de sistemas complejos para audiencias técnicas y no técnicas.

Recursos descargables

Cheatsheet de Símbolos

Referencia rápida de símbolos Mermaid: flowchart, sequence, state, ER y gitGraph

Markdown

Template Spec con Diagramas

Spec template extendida con secciones dedicadas a diagramas de flujo y arquitectura

Markdown

Solución Ejercicio Invitación

Solución de referencia al ejercicio de diagramar un sistema de gestión de invitaciones

Markdown
En este módulo
01
Hook El lenguaje natural es el peor vehículo para transmitir alcance

Hay una frase que todo PM escucha al menos una vez por sprint: «No entendí el alcance.»

Y no es porque el equipo sea lento. Es porque escribiste un párrafo de 500 palabras donde el lector tiene que construir el mapa mental en su cabeza mientras lee —y cada ingeniero construye un mapa diferente. Una frase como «cuando el usuario inicia sesión, si es administrador verá el dashboard, pero si es regular verá el inicio, a menos que tenga un permiso especial» no es un requerimiento: es un laberinto.

Los equipos técnicos no piensan en párrafos. Piensan en estados, transiciones, condiciones, bifurcaciones. Esto lleva a esto. Si pasa esto, entonces aquello.

Un diagrama de flujo no es un adorno estético: es el spec en su forma más pura. Cuando diagramas un flujo, te fuerzas a encontrar las ambigüedades que el texto oculta. ¿Qué pasa si el usuario no tiene internet? ¿Si la API responde con error? ¿Si son las 3 AM?

En este módulo no vas a aprender a hacer dibujos bonitos. Vas a aprender a traducir cualquier spec —por complejo que sea— en un diagrama que tu equipo pueda leer, criticar y ejecutar sin preguntar «¿y aquí qué pasa?».

Vamos.

Regla de oro

El texto te permite esconderte en «depende». El diagrama te obliga a dibujar todas las ramas.


02
Desarrollo teórico-práctico Los tipos de diagrama y el principio de inmunización visual

2.1. Por Qué el Texto Solo No Alcanza

El lenguaje natural es inherentemente ambiguo. No es que los requerimientos estén mal escritos: es que son interpretables de múltiples maneras.

56%
de los defectos de software nacen de requisitos mal especificados (IEEE)
500
palabras de prosa que un solo diagrama puede reemplazar

El problema del párrafo:

"El usuario podrá solicitar un reembolso dentro de los 30 días posteriores a la compra. El sistema verificará que el producto sea elegible, que no haya pasado la fecha límite, y que el usuario tenga una cuenta en buen estado. Si todo está bien, se procesará el reembolso; de lo contrario, se mostrará un mensaje de error."

Preguntas que un ingeniero se hace y el texto no responde:

  • ¿Qué es una cuenta en «buen estado»? ¿Sin deuda? ¿Sin reportes de fraude? ¿Con más de 30 días de antigüedad?
  • ¿El mensaje de error es el mismo para «producto no elegible» que para «fecha límite pasada»?
  • ¿Qué pasa si la verificación de elegibilidad tarda más de 5 segundos? ¿Timeout? ¿Mensaje?
  • ¿Qué pasa si el reembolso se procesa pero la pasarela de pago rechaza la transacción?

Todas estas preguntas existen. El texto simplemente no las obliga a hacerse visibles. Un diagrama no elimina la necesidad del texto: lo complementa. El texto explica el qué y el porqué; el diagrama muestra el cómo y el cuándo.

Juntos —texto + diagrama— forman un spec inmunizado contra la ambigüedad.

2.2. Los 6 Tipos de Diagramas para un PM Técnico

No todos los diagramas sirven para todo. Esta es la caja de herramientas visuales que todo PM debería dominar. Los 3 marcados con ★ son los que más te importan para aclarar alcance al equipo técnico:

Tipo Para Qué Sirve Cuándo Usarlo
★ Flowchart (Diagrama de Flujo) Secuencia de pasos con decisiones. El más universal. Cualquier flujo de usuario: registro, onboarding, compra, reembolso.
★ State Diagram (Máquina de Estados) Objeto que cambia de estado según eventos. Tickets, órdenes, suscripciones, documentos con ciclo de vida.
★ Sequence Diagram (Diagrama de Secuencia) Interacción entre actores/sistemas en el tiempo. Flujos donde intervienen múltiples servicios: API, webhook, base de datos, frontend.
Decision Tree (Árbol de Decisión) Múltiples condiciones que llevan a diferentes resultados. Reglas de negocio complejas: pricing, elegibilidad, routing, moderación.
BPMN (Business Process Model) Procesos con swimlanes (actores en carriles). Flujos cross-departmentales: aprobaciones, onboarding de clientes, compliance.
C4 Model / Diagrama de Arquitectura Componentes del sistema y sus relaciones. Contexto técnico: qué servicios existen, cómo se comunican, dónde vive cada cosa.

Los otros 3 (Decision Tree, BPMN y C4) son complementarios y los verás en contexto. Este módulo profundiza en los tres marcados.

2.3. Flowchart: El Universal

El flowchart es el diagrama más conocido y el más infravalorado. Su poder no está en su complejidad, sino en su precisión.

Símbolos estándar (ISO 5807):

Terminator
Inicio / Fin
Inicio o fin del flujo. 1 inicio, varios fines posibles.
Proceso
Hacer algo
Una acción. Verbo en imperativo, un nodo = una acción.
Decisión
¿Condición?
Bifurcación. Siempre con 2+ salidas etiquetadas (Sí/No).
Datos / E-S
Datos
Entrada/salida: leer un archivo, mostrar un mensaje, consultar una API.
Subproceso
Subflujo
Un proceso definido en otro diagrama. Divide flujos complejos.
Regla de oro para PMs

Si tu flowchart cabe en una pantalla y se entiende sin explicación, está bien. Si necesitas scroll o flechas que cruzan todo el diagrama, tu flujo es demasiado complejo: divídelo en sub-flujos.

Ejemplo: Flujo de Reembolso — el mismo párrafo de 2.1, ahora como mapa ejecutable:

Usuario solicita reembolso ¿Dentro de 30 días? ¿Producto elegible? ¿Cuenta en buen estado? Procesar reembolso ¿Error en pasarela? Reembolso procesado + Email «Fuera de plazo» «Producto no elegible» «Cuenta con restricciones» Notificar a soporte técnico No No No No
Cada rombo responde una pregunta que el texto dejaba abierta; cada flecha es una decisión de producto explícita, no un «depende».

2.4. State Diagram: El Ciclo de Vida de un Objeto

El state diagram modela cómo un objeto cambia de estado a lo largo del tiempo. Es el diagrama favorito de los ingenieros porque se traduce casi directamente a código.

Ejemplo: Estados de una Solicitud de Reembolso

PENDIENTE DE REVISIÓN EN PROCESO APROBADO RECHAZADO FALLIDO COMPLETADO asigna aprueba rechaza pasarela rechaza pasarela confirma
Estados verdes = final feliz · rojos = final por error. El diagrama revela estados huérfanos antes de producción.

Qué debe incluir un state diagram en un spec:

  • Estado inicial: ¿En qué estado nace el objeto?
  • Estados intermedios: ¿Por qué estados puede pasar?
  • Transiciones: ¿Qué evento causa cada cambio de estado?
  • Estado final: ¿Cuándo se considera terminado?
  • Transiciones inválidas: ¿Qué cambios de estado NO están permitidos?

Formato tabla para acompañar el diagrama:

Estado Actual Evento Condición Siguiente Estado Acción
Pendiente de Revisión Revisor asigna En Proceso Timestamp de inicio
En Proceso Revisor aprueba Producto elegible ∧ cuenta válida Aprobado Notificar usuario
En Proceso Revisor rechaza ¬ elegible ∨ ¬ cuenta válida Rechazado Enviar motivo
Aprobado Pasarela confirma Completado Enviar email + liberar fondos
Aprobado Pasarela rechaza Timeout ∨ fondos insuficientes Fallido Notificar a soporte
Fallido Supervisor re-intenta En Proceso Nueva transacción

Por qué esto le importa a tu equipo técnico: Porque cada fila de esta tabla es un caso de uso que el desarrollador puede implementar como unit test. Porque el diagrama revela estados huérfanos —¿qué pasa si una solicitud queda en 'Aprobado' pero la pasarela nunca responde?— antes de que lleguen a producción.

2.5. Sequence Diagram: La Coreografía Entre Sistemas

El sequence diagram muestra la interacción entre actores a lo largo del tiempo. Es indispensable cuando tu flujo involucra más de un sistema —frontend, backend, API externa, base de datos— porque revela problemas de timing que el texto oculta.

Ejemplo: Reembolso con Múltiples Sistemas

Usuario Frontend Backend Pasarela Base de Datos Solicitud POST /reembolso Verificar elegibilidad OK Guardar (INSERT) OK 201 Created Confirmación
El orden vertical es tiempo. Líneas sólidas = llamadas; punteadas = respuestas. Revela timing, acoplamiento y atomicidad.

Qué revela el sequence diagram que el texto no dice:

  • Timing: ¿El frontend espera la respuesta sincrónicamente o hay polling? ¿Cuánto timeout?
  • Acoplamiento: ¿Quién llama a quién? Si la pasarela cae, ¿el backend reintenta o devuelve error inmediato?
  • Consistencia: ¿La transacción es atómica? Si la pasarela confirma pero la DB falla al guardar, ¿qué pasa?
  • Latencia: ¿El usuario ve una pantalla de carga? ¿Cuánto espera? ¿Qué ve si la operación toma más de 10 segundos?

Para el PM: No necesitas dibujar todos los mensajes del protocolo HTTP. Necesitas dibujar las conversaciones de alto nivel entre sistemas que determinan la experiencia del usuario y los estados del dato.

2.6. El Principio de Inmunización Visual

Un spec inmunizado es aquel que ha sido sometido a un proceso sistemático de detección de ambigüedades.

🧭
Cambio de mentalidad

El diagrama no es el entregable: es el instrumento de detección de ambigüedades. Si no encontraste preguntas nuevas al dibujarlo, no estabas diagramando de verdad.

El proceso de inmunización en 3 rondas:

Ronda 1 — Traducción: Conviertes el texto del spec en un diagrama. En este proceso, descubres inevitablemente preguntas que el texto no responde. Las respondes o las marcas como "decisión pendiente".

Ronda 2 — Caminos infrecuentes: Recorres todas las ramas del diagrama buscando el caso infrecuente:

  • ¿Qué pasa si el usuario cierra el navegador en medio del flujo?
  • ¿Qué pasa si la API externa responde con 500?
  • ¿Qué pasa si son las 12:00 AM y el batch nocturno está corriendo?
  • ¿Qué pasa si el usuario tiene 2 sesiones abiertas?

Ronda 3 — Revisión por pares: Pasas el diagrama —sin el texto original— a un miembro del equipo técnico. Si lo entiende sin preguntar, está inmunizado. Si pregunta, actualizas el diagrama.

Marcador de inmunización:

Nivel Indicador
Inmunizado El equipo técnico implementa el flujo sin preguntas aclaratorias.
Protegido El equipo hace 1-2 preguntas pero el PM responde sin cambiar el diagrama.
Vulnerable El equipo encuentra 3+ ambigüedades que requieren re-dibujar.
Infectado El equipo implementa algo diferente a lo que el PM pensó. El diagrama no se usó.

03
Paso a paso técnico (Hands-on) Del texto al diagrama con Mermaid.js, Draw.io y Excalidraw

3.1. De un PRD a un Flowchart (Mermaid.js)

Mermaid.js es un lenguaje de diagramación basado en texto: escribes código, generas un diagrama. Esto es clave para un PM porque:

  • Vive en GitHub: los diagramas se renderizan en Markdown. Tu spec y tu diagrama están en el mismo archivo.
  • Es versionable: los cambios al diagrama se ven en el diff del PR. Nadie actualiza un .drawio sin avisar.
  • No requiere GUI: escribes en VS Code. No abres una herramienta externa.
Por qué Mermaid

Mermaid vive en GitHub y es versionable: tu spec y tu diagrama comparten archivo, commit y diff. El diagrama deja de quedarse obsoleto.

Paso 1 — Instalar soporte Mermaid en tu editor

VS Code: extensión "Markdown Preview Mermaid Support". GitHub: Mermaid funciona nativamente en cualquier .md.

Paso 2 — Sintaxis básica

graph TD
    A[Inicio] --> B{Sesión activa?}
    B -->|Sí| C[Dashboard]
    B -->|No| D[Pantalla de Login]
    D --> E[Credenciales válidas?]
    E -->|Sí| C
    E -->|No| D
Inicio ¿Sesiónactiva? Dashboard Pantalla Login ¿Credencialesválidas? No No
El mismo código Mermaid de arriba, ya renderizado: así lo verá tu equipo en el PR.

Paso 3 — Ejercicio guiado: Tu primer spec diagramado

Toma este requerimiento y diagramalo:

"El usuario puede agendar una demo desde la landing page. Debe seleccionar una fecha, una hora (en bloques de 30 minutos), e ingresar su email. Si el horario está disponible, se envía una confirmación. Si no, se sugieren 3 horarios alternativos. Si el email ya existe en la base de datos, se muestra un mensaje 'Ya tienes una demo agendada'."

Diagrama esperado:

graph TD
    A[Usuario en landing] --> B[Abre modal de agendamiento]
    B --> C[Selecciona fecha]
    C --> D[Selecciona hora]
    D --> E[Ingresa email]
    E --> F{Email ya tiene demo agendada?}
    F -->|| G[Mostrar: "Ya tienes demo"]
    F -->|No| H{Horario disponible?}
    H -->|| I[Reservar slot]
    I --> J[Enviar email confirmación]
    J --> K[Mostrar: "Demo confirmada"]
    H -->|No| L[Consultar 3 alternativas]
    L --> M[Mostrar alternativas]
    M --> N{Usuario selecciona alternativa?}
    N -->|| I
    N -->|No| O[Cerrar modal sin reserva]
Abre modal de agendamiento Selecciona fecha · hora · email ¿Email ya tienedemo? ¿Horariodisponible? Reservar slot + email «Demo confirmada» «Ya tienes demo agendada» Mostrar 3 alternativas No No si el usuario elige una
Render del agendamiento. Las 5 preguntas de abajo nacen de mirar este mapa, no el párrafo.

Preguntas que este diagrama revela y el texto original no cubría:

  1. ¿Qué pasa si la fecha seleccionada es hoy y la hora ya pasó?
  2. ¿Qué pasa si el usuario ingresa un email inválido?
  3. ¿Qué pasa si el servicio de disponibilidad falla (500)?
  4. Las "3 alternativas" ¿se generan automáticamente o el usuario debe escribir otra hora?
  5. ¿El modal tiene un límite de tiempo? ¿Expira la sesión?

Cada una de estas preguntas debe ser respondida en el spec antes de pasar a desarrollo. El diagrama no es el fin: es el mecanismo de detección.

3.2. De un Spec Técnico a un Diagrama de Secuencia (Draw.io)

Draw.io (diagrams.net) es gratuito, funciona offline, y exporta a PNG, SVG o XML. Es ideal para diagramas de secuencia y arquitectura que no necesitan vivir en Markdown.

Escenario: Tu equipo va a integrar una pasarela de pagos (Stripe) con tu plataforma SaaS. El flujo es:

"El usuario hace clic en 'Pagar', el frontend llama a nuestro backend, el backend crea un PaymentIntent en Stripe, Stripe devuelve un client_secret, el frontend lo usa para mostrar el formulario de tarjeta embebido (Stripe Elements), el usuario ingresa sus datos, Stripe procesa el pago y envía un webhook a nuestro backend confirmando el resultado."

Instrucciones para el diagrama de secuencia en Draw.io:

  1. Crea un diagrama nuevo → "Sequence Diagram" (en plantillas).
  2. Agrega 4 lifelines: Usuario, Frontend, Backend, Stripe.
  3. Dibuja los mensajes en orden cronológico.
Usuario Frontend Backend Stripe Clic «Pagar» POST /pago createPaymentIntent client_secret {clientSecret} Formulario (Elements) Ingresa tarjeta confirmPayment procesa 3D Secure webhook .succeeded resultado
El webhook llega después y por separado: por eso «¿quién registra el pago en la DB?» es la pregunta crítica.

Preguntas que el diagrama revela:

  • ¿Quién maneja el webhook? ¿El backend lo expone como endpoint público?
  • ¿Qué pasa si el webhook llega antes de que el frontend termine de renderizar?
  • ¿Quién registra el pago en la base de datos? ¿El webhook? ¿La respuesta del confirmPayment?
  • ¿Qué pasa si 3D Secure requiere redirección? ¿El frontend la maneja?
  • ¿Cuál es el timeout del client_secret?

3.3. De una Regla de Negocio a un Árbol de Decisión (Excalidraw)

Excalidraw es una pizarra blanca digital con un estilo hand-drawn que baja la barrera de entrada. Ideal para sesiones de Discovery donde el diagrama evoluciona en tiempo real.

Escenario: Regla de pricing compleja para un SaaS multicliente:

"El precio base es $10/mes por usuario. Si el cliente tiene más de 50 usuarios, aplica 15% de descuento. Si tiene más de 200, 25%. Si el contrato es anual, hay 2 meses gratis. Si el cliente está en Latinoamérica, el precio se ajusta por PPP con un factor de 0.7. Si el cliente es nonprofit, el precio base es $5/mes."

Árbol de Decisión:

graph TD
    A[Cliente solicita cotización] --> B{Es nonprofit?}
    B -->|| C[Base: $5/usuario/mes]
    B -->|No| D[Base: $10/usuario/mes]
    C --> E{Región?}
    D --> E
    E -->|Latam| F[Ajuste PPP × 0.7]
    E -->|Resto| G[Sin ajuste]
    F --> H{Usuarios?}
    G --> H
    H -->|1-50| I[Sin descuento]
    H -->|51-200| J[Descuento 15%]
    H -->|201+| K[Descuento 25%]
    I --> L{Contrato anual?}
    J --> L
    K --> L
    L -->|| M[-2 meses gratis  precio efectivo = anual / 14 * 12]
    L -->|No| N[Precio mensual estándar]
¿Es nonprofit?
→ Base $5/usuario/mes
No → Base $10/usuario/mes
¿Región?
Latam → ajuste PPP × 0.7
Resto → sin ajuste
¿Usuarios?
1–50 → sin descuento
51–200 → descuento 15%
201+ → descuento 25%
¿Contrato anual?
→ −2 meses gratis (anual / 14 × 12)
No → precio mensual estándar
El precio se acumula descendiendo por las 4 decisiones. Despliega cada nivel; en Excalidraw moverías estas ramas en vivo durante Discovery.

Por qué Excalidraw es la herramienta correcta aquí: Porque durante una sesión de Discovery, el árbol cambia constantemente. "Ah, ¿y si el cliente tiene 500 usuarios pero es nonprofit?" — agregas una rama. "¿Y si el descuento anual no es acumulable con el descuento por volumen?" — corriges una condición. Excalidraw permite este caos controlado que Draw.io no soporta bien.


04
El workflow del diagrama en tu ciclo de spec Dónde vive cada diagrama, cuándo dibujarlo y cómo se vuelve tareas

El diagrama no es un artefacto aislado. Tiene un lugar específico dentro del Spec-Driven Development:

4.1. ¿Dónde Vive Cada Diagrama en tu Spec?

Sección del Spec Diagrama Recomendado Qué Representa
Contexto (¿Por qué esto existe?) C4 Nivel 1: Contexto El sistema en su ecosistema
Flujo Principal (Happy path) Flowchart Secuencia ideal sin errores
Flujos Alternos (Errores, bordes) Flowchart (ramas) Cada condición que se desvía del happy path
Reglas de Negocio (Condiciones complejas) Decision Tree Mapeo condición → resultado
Interacciones Técnicas (APIs, webhooks) Sequence Diagram Coreografía entre sistemas
Estados (Ciclo de vida de un objeto) State Diagram Nacimiento, transformaciones, muerte

4.2. El Momento Exacto para Diagramar

No diagrames al inicio. Diagramas en el momento exacto entre la escritura del spec y la revisión técnica.

Día 1
Escribes
el spec en texto (PRD, RFC)
Día 2
Diagramas
los flujos · identificas ambigüedades
Día 3
Cierras
ambigüedades · actualizas spec + diagramas
Día 4
Revisión
técnica: el equipo lee spec + diagramas juntos
Día 5
Planning
el diagrama se convierte en tareas
Regla

No lleves un spec a revisión técnica sin diagramas. Si el equipo no tiene un mapa visual, cada ingeniero construirá uno distinto en su cabeza.

4.3. Diagrama como Fuente de Tareas

Cada rama de un flowchart es candidata a tarea. Cada transición de un state diagram es un caso de prueba.

Ejemplo: Del flowchart de demo agendamiento, las tareas emergen naturalmente:

Rama del Diagrama Tarea Tipo
Usuario selecciona fecha → horas disponibles [FE] Modal de agendamiento con selector de fecha Feature
Horario disponible = Sí → reservar slot [BE] Endpoint POST /demo/reserve Feature
Horario disponible = No → consultar alternativas [BE] Algoritmo de sugerencia de horarios Feature
Email ya existe → mostrar mensaje [BE] Validación de duplicados en agendamiento Validación
Servicio de disponibilidad falla → ? [BE] Manejo de error en consulta de disponibilidad Error handling
Usuario cierra modal en medio del flujo → ? [FE] Estado inconsistente: limpiar slot reservado parcialmente Estado borde

Esto no es un ejercicio teórico. Cada tarea del sprint puede trazarse a una rama específica del diagrama. Si el equipo sabe de qué rama viene cada tarea, nunca preguntará "¿esto es parte del alcance?"


⚠ Errores comunes
  • Error: diagramar absolutamente todo. Corrección: diagrama solo donde el texto genera interpretaciones distintas; el resto es decoración que envejece mal.
  • Error: flowcharts con símbolos inventados. Corrección: usa ISO 5807: el rombo decide, el rectángulo procesa, el paralelogramo es entrada/salida. El estándar existe para no explicar la leyenda.
  • Error: publicar código Mermaid donde no se renderiza. Corrección: acompaña el bloque de código con la imagen dibujada: la página queda auto-demostrativa.
  • Error: estados que en realidad son actividades ("procesando..."). Corrección: en una state machine, un estado es una espera estable entre eventos; la actividad va en la transición.
  • Error: diagramas huérfanos que nadie actualiza. Corrección: el diagrama vive junto al spec y se versiona con él; un diagrama desactualizado es peor que ninguno.
05
Rúbrica de evaluación Tres criterios: cobertura, autocontención y trazabilidad a tareas
Criterio No Aprobado (0) Aprobado (1) Sobresaliente (2)
1. El diagrama cubre los 3 caminos: feliz, error, borde El diagrama solo muestra el happy path. No hay ramas de error ni condiciones límite. El diagrama incluye al menos 1 camino de error y 1 condición límite, pero faltan otros bordes evidentes (timeout, cancelación, datos inválidos). El diagrama agota sistemáticamente los caminos: happy path, al menos 2 errores documentados, y al menos 2 bordes (estado inconsistente, concurrencia, cancelación, datos corruptos).
2. El diagrama es auto-contenido (no necesita texto para entenderse) El diagrama es ilegible sin leer el spec. Las flechas no tienen etiquetas claras, hay nodos desconectados, o usa símbolos no estándar sin leyenda. El diagrama se entiende en su mayoría, pero requiere leer el spec para entender 1-2 nodos ambiguos o decisiones no representadas. Un ingeniero que solo ve el diagrama (sin spec) puede implementar el flujo sin preguntar. Cada flecha tiene etiqueta, cada decisión tiene condición explícita, no hay nodos colgantes.
3. El diagrama se traduce directamente a tareas Las tareas no se corresponden con las ramas del diagrama. El backlog y el diagrama parecen de flujos diferentes. Al menos el 60% de las tareas del sprint son trazables a ramas específicas del diagrama, pero algunas quedan huérfanas o parecen inventadas después. Toda tarea del sprint tiene una rama correspondiente en el diagrama. El equipo puede señalar cualquier tarea y decir "esto es la rama de error cuando la pasarela no responde".

Aprobación: 2 de 3 criterios en "Aprobado" o superior.


06
Ejercicio integrador Inmuniza el spec de «invitación a workspace» con diagramas
🧪 Tu entregable

Escenario: Tu equipo va a construir un sistema de «invitación a workspace» para un SaaS colaborativo:

"Un usuario administrador puede invitar a nuevos miembros a su workspace ingresando su email. El sistema envía un email con un link de invitación válido por 7 días. Si el invitado ya tiene cuenta, al hacer clic en el link se une al workspace automáticamente. Si no tiene cuenta, debe registrarse primero y luego se une."

"El administrador puede revocar invitaciones pendientes. Si la invitación expira, se marca como expirada y el administrador puede reenviarla. Un email puede tener máximo 3 invitaciones activas simultáneas; si ya hay 3 y se intenta invitar de nuevo, el sistema rechaza la operación."

Produce:

  1. Flowchart del proceso completo (Mermaid.js inline en un spec simulado).
  2. State Diagram del objeto «Invitación» con todos sus estados y transiciones.
  3. Mínimo 3 preguntas de ambigüedad que el texto original no responde y que el diagrama reveló.
  4. Lista de tareas derivadas de las ramas del diagrama.

Entrega — un archivo Markdown con:

  • Spec simulado (2-3 párrafos con el contexto).
  • Diagramas en Mermaid.js.
  • Tabla de ambigüedades identificadas.
  • Tabla de tareas → rama del diagrama.
  • Nota de auto-evaluación según la rúbrica.

Apóyate en el kit m15-logic-flows/: template-spec-con-diagramas.md · cheatsheet-simbolos-diagramas.md · solucion-ejercicio-invitacion.md

  • ✅ Checklist de inmunización visual (antes de compartir el spec)
  • El flowchart tiene 1 inicio, 1+ fines, decisiones etiquetadas y ramas de error.
  • El state diagram tiene estado inicial, intermedios, final y todas las transiciones.
  • El sequence diagram incluye todos los actores y el orden cronológico correcto.
  • No hay nodos desconectados ni flechas sin destino.
  • El diagrama se entiende sin leer el spec (pruébalo con un compañero).

07
Integración con el curso Cómo se conecta con los módulos 3, 5, 7 y 14

7.1. Conexión con Módulo 3 (Spec-Driven Development)

Los diagramas de este módulo son el anexo visual del Spec Kit que construiste en Módulo 3. Cada template del Spec Kit (PRD, RFC, ADR) debería incluir una sección de diagramas al final. El proceso de inmunización visual es el paso que ocurre entre la escritura del spec y la revisión técnica.

7.2. Conexión con Módulo 5 (Backlog)

Las tareas derivadas de los diagramas alimentan directamente tu backlog paramétrico. Cada rama del diagrama produce una tarea con esfuerzo estimable y valor asignable. Si tienes 3 features con el mismo WSJF score, la que tenga el diagrama más completo —menos ambigüedades— debería ir primero: está más cerca de ser ejecutable.

7.3. Conexión con Módulo 7 (CLI para PMs)

Comando útil para diagramar desde terminal:

# Generar diagrama Mermaid desde un archivo .mmd
npx @mermaid-js/mermaid-cli generate flujo.mmd -o diagrama.png

# Ver spec + diagrama en la terminal (si usas GitHub CLI)
gh view spec.md --comments

7.4. Conexión con Módulo 14 (QBR)

En el QBR final, los diagramas son parte del portafolio que presentas al panel. Un spec sin diagramas se evalúa como incompleto. Los diagramas demuestran que el PM no solo sabe escribir requerimientos, sino que sabe comunicarlos en el lenguaje del equipo técnico.

🎯 Lo que te llevas
  • 3 diagramas clave: Flowchart (flujo + decisiones), State Diagram (ciclo de vida de un objeto) y Sequence Diagram (coreografía entre sistemas).
  • El diagrama es el instrumento de detección de ambigüedades, no el entregable: si no surgieron preguntas nuevas, no diagramaste de verdad.
  • Mermaid para lo que vive en GitHub, Draw.io para secuencia/arquitectura, Excalidraw para Discovery en vivo.
  • Cada rama del diagrama es una tarea; cada transición, un caso de prueba. Diagrama entre el spec y la revisión técnica, nunca después.
  • Un buen diagrama no explica el alcance: lo revela. La ambigüedad no sobrevive al escrutinio visual.

Kit del Módulo (K50-K52)

# Kit Formato Descripción
K50 Plantilla de Spec con Diagramas Markdown Spec template con secciones predefinidas para flowchart, state diagram y sequence diagram. Incluye ejemplos de Mermaid.js.
K51 Cheatsheet de Símbolos de Diagramas Markdown/PDF Referencia rápida: símbolos ISO flowchart, notación de state diagram, lifelines de sequence diagram.
K52 Ejercicio de Inmunización: Caso Invitación Markdown Spec del ejercicio integrador con diagramas completos (solución de referencia para el alumno).

Ubicación: kits/m15-logic-flows/


"Un buen diagrama no explica el alcance: lo revela. La ambigüedad no sobrevive al escrutinio visual."

Kit: Diagramas de Flujo

ArchivoDescripción
⬇ template-spec-con-diagramas.md Plantilla de spec con secciones para flowchart + state diagram + sequence diagram
⬇ cheatsheet-simbolos-diagramas.md Cheatsheet de símbolos: ISO flowchart, state notation, sequence lifelines
⬇ solucion-ejercicio-invitacion.md Solución del Ejercicio de Inmunización con diagramas completos

📁 kits/m15-logic-flows/