Story Walkthrough (Explicación tipo historia)

¿Qué hace Story Walkthrough (Explicación tipo historia)?

El usuario quiere entender un problema que no ha vivido desde dentro. No conoce los componentes, el vocabulario ni el orden en que ocurren las cosas. Una lista de hallazgos o un resumen de diferencias no le ayuda. Una historia sí: presenta cada actor una vez, luego muestra lo que hace cada uno, en el orden en que sucede, hasta que el fallo surge de forma natural.

Investiga primero. La historia solo es tan buena como los hechos que la respaldan, así que lee el código, los registros (logs), los tickets, los documentos y el historial antes de escribir. Si la investigación ya ocurrió antes en la conversación, reutilízala en lugar de repetirla.

Forma de la respuesta

Abre con una línea que establezca el marco, por ejemplo: "Aquí tienes toda la historia desde el principio, sin asumir que conoces el código." Luego usa estas secciones. Omite una sección que no tenga nada real que decir, en lugar de rellenarla.

Los personajes

Presenta a cada actor que la historia necesita, y nada más: componentes, clases, mensajes, temporizadores, datos y, para un proceso, las personas, equipos, formularios y configuraciones involucrados. Dale a cada uno un nombre en negrita y una o dos frases claras sobre qué es y qué hace en esta historia.

• Nombra cada personaje con precisión y enlázalo al código. Escribe price_cache_key() con un enlace archivo:línea, no "el constructor de claves". Una etiqueta vaga hace que el lector se detenga y pregunte qué significa. Si un personaje abarca varias piezas de código (un método más los enlaces del framework que lo rodean), dilo aquí. Para un problema fuera del código, enlaza la fuente en su lugar: el documento y el paso, el campo del formulario o la ruta de configuración.
• Elige una metáfora física para el mecanismo abstracto y mantenla durante toda la historia. Por ejemplo, las cabeceras de los mensajes se convierten en "notas grapadas a un sobre", una caché se convierte en "una pizarra", un bloqueo se convierte en "una llave". Introduce la metáfora junto al nombre real ("la caché de precios, una pizarra al lado de cada servidor web") para que el lector pueda relacionarla con el código. No cambies de metáfora a medio camino y no apiles dos.
• Da la regla que sigue cada personaje, expresada como el pensamiento del propio personaje en cursiva: "Hoy es la fecha que muestre mi reloj." Los errores y fallos de proceso suelen provenir de dos reglas razonables que chocan, y esto hace visible el choque más adelante.

Capítulos

Cuenta lo que sucede en orden temporal, un capítulo por paso: ## Capítulo 1: Un comprador mira los precios antes de medianoche, ## Capítulo 2: Llegan los nuevos precios, y así sucesivamente. Títulos cortos que digan lo que sucede.

• Mantén cada capítulo corto: unas pocas frases o unas pocas viñetas.
• Pon en negrita el detalle clave del capítulo, el único hecho que el lector no debe perderse ("la importación borra la esquina equivocada de la pizarra").
• Cuando dos cosas sucedan al mismo tiempo, dale su propio capítulo y muestra ambos lados uno tras otro.
• El capítulo del fallo cita el mensaje de error exacto como una cita en bloque y dice qué código lo captura y qué registra.

Por qué el síntoma se ve como se ve

Después del fallo, explica el patrón observado: por qué solo las primeras horas, por qué solo en algunos servidores, por qué solo tras un reinicio. Relaciónalo con lo que el ticket o los registros realmente mostraron. Esta es la comprobación de que la historia es correcta, así que mantenla.

Cuando el problema es un riesgo, no un fallo

A veces la historia trata sobre algo que podría salir mal: un comentario de revisión, un error latente, un "y si...". No ha fallado nada, así que no hay una línea de registro ni un síntoma de ticket que ancle la historia. Cuéntalo de forma diferente, porque un lector que vea un error citado asumirá que ocurrió.

• Di pronto que no ha ocurrido. Indica en la línea de apertura o en el primer capítulo que se trata de un posible fallo encontrado al leer el código, no visto en registros o pruebas.
• Detalla las condiciones. El capítulo del fallo enumera exactamente qué debe ser cierto para que ocurra el fallo, como condiciones numeradas ("1. la operación llama a otro servicio después de que el ámbito se cerró, y 2. no se abre un nuevo ámbito alrededor de esa llamada"). Luego nombra qué saldría mal: la aserción, el tipo de excepción, la línea. No cites un mensaje de error que nadie ha visto. Si nombras una excepción, di que proviene de leer el código.
• Reemplaza "por qué el síntoma se ve así" con "por qué nada lo alcanza hoy". Revisa cada llamante o flujo real y muestra qué condición no cumple, con enlaces. Esta sección lleva el peso de la historia, porque el lector debe decidir si el riesgo está activo.
• Busca los llamantes que no has revisado. Escribir la lista de "qué tan grave es" para un riesgo es donde aparecen los caminos no revisados: una llamada hecha fuera del lugar habitual, un transporte diferente, una tarea en segundo plano. Enumera cada uno como "no revisado" en lugar de omitirlo, y di qué evidencia hay (por ejemplo, una ejecución de prueba limpia que lo ejerció sin rastrearlo).
• Compara costos en la sección de solución. Una solución para un riesgo puede traer de vuelta un fallo real. Si es así, dilo claramente: la solución cambia un riesgo que nada alcanza por un fallo que ocurre.

Por qué empezó ahora

Si el comportamiento es una regresión, di qué cambió, cuándo y por qué ese cambio tenía sentido por sí solo. Nombra el PR o commit primero en palabras, con el ID entre paréntesis. El lector necesita saber que el cambio anterior no fue descuidado, solo incompleto.

Qué tan grave es

Enumera el impacto real: datos, números, alertas, ruido en registros. Separa lo confirmado de lo inferido, porque el lector repetirá estas afirmaciones a otros.

• Marca cada afirmación como revisada (y cómo: una prueba, una consulta de registro, una lectura de ruta de código de principio a fin) o como no revisada.
• No escribas "los datos están bien" a menos que algo lo haya verificado. Una afirmación plausible que resulta ser falsa cuesta más confianza que un "no revisado aún" honesto.

Cómo solucionarlo

Da las opciones de menor a mayor (por ejemplo, una solución rápida y una solución adecuada), qué cambia cada una en términos de la historia ("dale a ambos personajes el mismo calendario") y sus limitaciones. Termina con una breve recomendación.

Estilo

• Palabras claras. Define cada término la primera vez que aparece, o déjalo fuera.
• Mantén los identificadores de código entre comillas invertidas junto a la metáfora, para que la historia siga siendo trazable hasta el código.
• Prefiere párrafos cortos y viñetas sobre bloques largos.
• Sigue las reglas de estilo de escritura del usuario de su archivo CLAUDE.md o AGENTS.md.

Después de la historia

Espera preguntas de seguimiento sobre un personaje ("¿Entonces X es el manejador?"). Responde fijando el personaje al código exacto: enumera qué se ejecuta, en orden, con enlaces archivo:línea, y di qué parte hace lo que importa. Si la pregunta muestra que la historia original nombró algo de forma vaga, corrige el nombre en tu respuesta en lugar de defenderlo.

Ejemplo

references/example-stale-prices.md contiene una historia completa escrita en este estilo para un error de caché obsoleta, más notas sobre lo que se equivocó. Léelo antes de escribir tu primera historia en una sesión, para calibrar la extensión y el tono.