Comunicar con el equipo: acordar el comportamiento antes de programarlo

El desacuerdo sobre el comportamiento de un producto no desaparece: se aplaza. Se aplaza desde la reunión de definición, donde nadie preguntó qué pasa si el usuario vuelve atrás a mitad del pago, hasta el día en que un ingeniero se topa con la ambigüedad y la resuelve solo, con el criterio que tenga a mano y sin dejar rastro de que ha tomado una decisión de producto. Ese aplazamiento es el impuesto más caro del desarrollo de software, porque el precio de resolver una ambigüedad crece con todo lo que se ha construido sobre ella. Lo que sigue no es una lección sobre diagramas bonitos para presentaciones, sino sobre un uso muy concreto del statechart: como superficie donde el desacuerdo aflora temprano, con coordenadas, delante de las personas que pueden resolverlo.

El diagrama como objeto frontera

En 1989 Susan Leigh Star y James Griesemer describieron los objetos frontera: artefactos que habitan varios mundos sociales a la vez, lo bastante plásticos para que cada comunidad los use según sus necesidades y lo bastante robustos para conservar una identidad común. Un mapa de un parque natural es su ejemplo canónico: el biólogo, el cazador y el administrador ven cosas distintas en él y sin embargo hablan del mismo territorio. El statechart funciona exactamente así. Para diseño es la secuencia de pantallas y sus transiciones; para producto son las reglas de negocio y lo que está permitido; para ingeniería es la especificación de implementación. Nadie tiene que aprender el lenguaje del otro porque el artefacto ya habla los tres.

La plasticidad del objeto frontera tiene un límite que conviene respetar: funciona mientras el modelo se mantenga en el plano del comportamiento observable y no descienda al de la implementación. En cuanto en el lienzo aparecen estados que representan pasos internos —esperando la respuesta del segundo microservicio, reintentando la conexión con la caché—, diseño y producto dejan de reconocerse en el artefacto y vuelven a delegarlo en ingeniería, que es exactamente lo que se quería evitar. Si esos estados internos son necesarios, van en una submáquina propia; el modelo compartido conserva un único estado visible que los engloba.

Eso lo distingue de los dos candidatos habituales. Un documento de requisitos en prosa es robusto pero nada plástico: solo lo lee bien quien lo escribió, y su corrección no se puede comprobar. Un prototipo interactivo es plástico pero no robusto: enseña un camino feliz y calla sobre todos los demás, que es donde vive el trabajo. El statechart es el único artefacto de la mesa que muestra a la vez lo que ocurre y lo que no puede ocurrir, y que además es ejecutable, de modo que la discusión se puede zanjar recorriéndolo en lugar de recordándolo.

Hay un efecto secundario que conviene aprovechar deliberadamente: los nombres de los estados se convierten en el vocabulario común del equipo, en el sentido que Eric Evans llamó lenguaje ubicuo. El nombre que se pone a un estado en el lienzo termina en el código, en las trazas de inspección, en los mensajes de error, en los nombres de las pruebas y en la conversación del canal de soporte. Por eso nombrar es un acto de diseño de producto y no una tarea técnica: pendiente_de_verificacion y bloqueado describen la misma situación técnica y comunican promesas distintas al usuario, y esa diferencia debe decidirse en la mesa donde está producto, no tres semanas después en una revisión de código.

El protocolo de la sesión de modelado

Una sesión de modelado bien conducida dura entre sesenta y noventa minutos, reúne a una persona de producto, una de diseño y una o dos de ingeniería, y produce como acta el esqueleto de una máquina, no un documento sobre ella. El orden importa porque cada paso desbloquea el siguiente.

flowchart TD
A[Enumerar los modos excluyentes] --> B[Enumerar los eventos del usuario y del mundo]
B --> C[Rellenar la matriz de modo por evento]
C --> D[Decidir cada celda sin dejar ninguna en blanco]
D --> E[Nombrar los estados nuevos que han aparecido]
E --> F[Simular delante del grupo]
F -->|aparece una sorpresa| C
F -->|nadie se sorprende| G[El modelo es el acta y entra al repositorio]

El paso uno esconde una criba que vale por sí sola lo que dura la reunión: al intentar enumerar modos excluyentes, el grupo descubre que la mitad de lo que llamaba estados eran datos. Que el carrito tenga tres artículos, que el usuario sea premium o que el formulario esté a medias no son modos, son valores del contexto; el modo es si el carrito está en edición, en pago o cerrado. Separar el modo del dato es la operación conceptual más difícil de la sesión y también la más productiva, porque los productos que acumulan estados fantasma —cargandoConDatosViejosDeUsuarioPremium— sufren exactamente de no haberla hecho.

El paso tres es el que hace el trabajo, y merece una herramienta explícita: la matriz de estado por evento, que es la tabla de transiciones del nivel 1 usada como instrumento de reunión. Su virtud es que hace visible el hueco: una celda vacía es una pregunta que alguien tiene que responder ahora, no una omisión que nadie percibe. La regla de oro es que ninguna celda puede quedar en blanco ni marcada como no aplicable; hay que elegir explícitamente entre ignorar el evento, encolarlo, rechazarlo con un mensaje o transicionar.

Sobre el tamaño del grupo, la experiencia es consistente: cuatro personas funcionan, ocho no. La sesión exige decidir en voz alta y con rapidez, y por encima de cierto número el coste de coordinar la conversación supera al de modelar. Si hay más partes interesadas de las que caben, se modela con el grupo pequeño y se presenta el resultado simulándolo, que ocupa diez minutos y provoca las objeciones importantes igual de bien. Lo que no funciona nunca es enviar el modelo por escrito y pedir comentarios: sin la simulación delante, nadie descubre lo que falta.

Esa celda con dos opciones separadas por una barra es el patrón que más valor produce en la sesión: no es un fallo del modelo, es una decisión de producto que acaba de hacerse visible tres semanas antes de lo habitual. Qué debe pasar si la sesión caduca mientras el cobro está en vuelo es una pregunta con consecuencias legales y de soporte que nadie iba a formular mirando un prototipo, y que la matriz obliga a formular porque hay una casilla vacía en el centro de la pantalla compartida.

Los estados que el diseño olvida

Un catálogo de pantallas describe el sistema cuando todo va bien, porque la maqueta se dibuja sobre datos que existen y respuestas que llegan. El repertorio de situaciones que faltan es sorprendentemente estable entre productos y entre equipos, hasta el punto de que conviene llevarlo impreso a la sesión y recorrerlo como lista de comprobación antes de dar por cerrado el modelo.

Conviene además introducir en la sesión una pregunta que casi nadie hace y que reordena el modelo entero: qué eventos puede emitir el mundo sin que el usuario haga nada. La respuesta suele incluir la respuesta del servidor, el vencimiento de un plazo, la desconexión, una notificación entrante o el mismo usuario actuando desde otro dispositivo. Los productos que fallan de formas raras suelen fallar exactamente ahí, porque su modelo mental implícito supone que el sistema solo cambia cuando alguien toca la pantalla, y ese supuesto es falso en cualquier aplicación conectada.

Hay una asimetría en el catálogo que conviene explotar: los estados olvidados casi nunca son de camino feliz, y por tanto casi nunca los reclama nadie hasta que un usuario real se topa con ellos. Nadie escribe una petición de soporte diciendo que falta el estado de espera larga con opción de cancelar; escribe que la aplicación se le quedó colgada. Esto significa que la deuda de estados no aparece en el flujo habitual de peticiones de producto, y que la sesión de modelado es prácticamente el único momento en que puede detectarse antes de convertirse en incidencias.

Hay un beneficio adicional para diseño que rara vez se anticipa y que sirve para ganarse a la disciplina más escéptica: la accesibilidad se modela junto al comportamiento. Cada estado tiene un anuncio para el lector de pantalla, una gestión del foco y una decisión sobre si el contenido cambia de forma disruptiva. Cuando los estados están enumerados, esas decisiones son una columna más de la matriz, en lugar de una revisión que llega al final y descubre que faltan cuatro pantallas.

Del acuerdo al criterio de aceptación

El modelo acordado no termina en el acta: se convierte en el criterio con el que se verificará el trabajo. Un camino a través de la máquina —una secuencia de eventos desde el estado inicial hasta uno terminal— es exactamente lo que un criterio de aceptación intenta expresar en prosa, con la diferencia de que el camino es ejecutable y la prosa no. El nivel anterior mostró cómo generar esos caminos desde el modelo; aquí se cobra el uso organizativo de esa capacidad.

// Los caminos del modelo son la lista de criterios de aceptacion.
import { getShortestPaths } from '@xstate/graph'
import { pago } from './pago'

const caminos = getShortestPaths(pago, {
  events: [{ type: 'PAGAR' }, { type: 'CANCELAR' }, { type: 'CADUCA_SESION' }],
})

for (const camino of caminos) {
  const eventos = camino.steps.map((s) => s.event.type).join(' luego ')
  console.log(`${eventos} termina en ${JSON.stringify(camino.state.value)}`)
}

Antes de nada hay que enseñar a leer el diagrama, y lleva menos de lo que la gente teme. Bastan tres convenciones dichas en voz alta al empezar: una caja es una situación en la que el sistema puede estar y solo puede estar en una a la vez, una flecha es algo que ocurre y su etiqueta es el nombre de eso que ocurre, y la ausencia de flecha significa que ese algo no tiene efecto en esa situación. Con esas tres frases cualquier persona de producto o de diseño participa de pleno derecho. Quien introduce el statechart empezando por la jerarquía, las regiones paralelas o la historia pierde a la sala en noventa segundos y concluye erróneamente que el formalismo no es para equipos mixtos.

Conviene generar los caminos con el conjunto de eventos acordado en la sesión y no con todos los posibles, porque el objetivo aquí no es la cobertura exhaustiva —eso pertenece al nivel de pruebas— sino producir una lista que una persona de producto pueda leer entera sin perder la paciencia. Diez o quince caminos nombrados en lenguaje de dominio son revisables; ciento cuarenta no lo son y provocan que nadie los mire, que es peor que no haberlos generado.

La lista que imprime ese fragmento se puede pegar en la tarjeta de trabajo y revisarla con producto en cinco minutos. Su valor no es la automatización, que es modesta, sino el cambio de carga de la prueba: en lugar de que alguien invente los casos que se le ocurren, el modelo enumera los que existen y la conversación pasa a ser cuáles de estos caminos importan y cuáles se aceptan sin cubrir. Es una discusión mucho más honesta que la habitual, porque parte de un inventario completo en lugar de una muestra sesgada por lo que cada cual recuerda.