Cierre de la deriva del PRD encontrada en una revisión de código

Greenhouse tiene un documento PRD anterior a la mayor parte de la implementación. Es la especificación que escribí antes de que existiera código alguno, y como toda especificación que convive con una base de código durante unos meses, empezó a alejarse de lo que la app realmente hace. La misma revisión completa de la app que sacó a la luz el estante de cosecha invisible señaló cuatro puntos donde el documento y el código no coincidían. Este registro trata sobre el cierre de esos puntos.

Ninguno de estos era un error. Todos eran lugares donde había tomado una decisión real en el código y nunca había vuelto a actualizar el párrafo que describía la pregunta abierta.

Los archivos espejo nunca dijeron que se sobrescribirían

Greenhouse usa SQLite como fuente de verdad para el estado de un proyecto, y luego escribe un archivo project.md o idea.md sencillo en la carpeta del proyecto, para que los datos sigan siendo legibles incluso si la app no se vuelve a abrir. El PRD había dejado abierta la cuestión de si las ediciones a ese archivo se fusionarían de vuelta a la base de datos, o si la base de datos simplemente prevalecería. En la práctica, construí una regeneración unidireccional hace meses: cada escritura relevante reescribe el archivo desde cero. Nunca dejé esa decisión por escrito, y peor aún, el archivo mismo no daba ninguna pista de que editarlo a mano no servía de nada. Así que agregué una línea al inicio de ambos archivos: Auto-generated by Greenhouse. Edits here will be overwritten. Un cambio pequeño, pero es la diferencia entre perder una edición en silencio y saber de entrada que no conviene hacerla.

Dos parámetros que antes eran uno

El PRD describía la cuota semilla (un incentivo para capturar un lote inicial de ideas) y la advertencia de inventario bajo (un incentivo para capturar más una vez que el inventario empieza a escasear) como si fueran dos valores configurables separados. En algún momento del camino los fusioné: la advertencia de inventario bajo simplemente se activa cuando la cantidad de elementos utilizables cae por debajo de la cuota semilla. Un parámetro, dos comportamientos. El documento no se había puesto al día, así que reescribí la viñeta de inventario bajo para decir explícitamente que su umbral es la cuota semilla, no algo configurable de forma independiente.

Una regla sin explicación de por qué existe

El asistente de incorporación recorre las reglas centrales de Greenhouse como un conjunto de tarjetas, cada una con una razón de una línea que explica por qué existe. No había tarjeta para el temporizador de inactividad de la bóveda: un proyecto guardado en la bóveda vuelve silenciosamente a revisión después de 14 días, y hasta ahora nada le avisaba al usuario que eso se aproximaba. Simplemente aparecía un día como un aviso de “Rescatar o Conservar” sin ningún contexto. Agregué una quinta tarjeta que lo explica. Ese mismo componente de recorrido también funciona como el diálogo de “¿por qué estas reglas?” accesible desde el pie del panel, así que la corrección aparece en ambos lugares sin trabajo adicional.

Una afirmación que el panel en realidad no respalda

La sección de flujo diario afirmaba que el panel “refleja lo que se hizo hoy.” Eso solo es cierto para la captura. La app registra si se anotó una idea nueva hoy, pero no registra si se revisó una idea madura o si se trabajó en un proyecto activo hoy, solo muestra lo que está listo en ese momento para esas acciones, sin importar cuándo se tocó por última vez. Reescribí la afirmación para que coincidiera con lo que el código realmente hace, en vez de dejar crecer en silencio una deuda de funcionalidad contra una frase que nadie volvía a leer.

Lección

Un PRD que no se actualiza junto con el código deja de ser documentación y pasa a ser un registro histórico de lo que se pretendía construir. Ninguno de estos cuatro puntos fue difícil de corregir una vez encontrado, el trabajo consistió simplemente en notar que se habían desviado. Vale la pena hacer una pasada periódica, sobre todo después de cualquier issue que cambie el comportamiento sin una edición del documento en el mismo commit.