Implementando Plum para Gobernanza de Decisiones en Código

¿Y si te dijera que tu “spec” es una tarjeta de bienvenida para el caos si no la conviertes en evidencia viva?

Tiempo estimado de lectura: 6 min

• Plum convierte decisiones de diseño y agentes en evidencia rastreable ligada a commits.
• Fallar commits a propósito es el checkpoint que fuerza la aprobación humana y evita decisiones no registradas.
• El flujo incluye init, extracción de decisiones, bloqueo de commits si hay decisiones pendientes y sincronización spec↔tests↔código.
• Limitaciones reales: Pytest-only ahora, backfill difícil, deduping fuzzy y riesgo de ruido de interrupción.

Introducción

Poca gente habla claro de esto: cuando un Product Manager cambia una regla, la pregunta real no es “¿habrá que tocar el código?” sino “¿cómo sabré mañana quién decidió qué, por qué y con qué pruebas?”. Spoiler: la mayoría no lo sabe. Y con agentes de IA metidos en la cocina, ese “no saber” se vuelve que arda todo en silencio.

Esto no es teoría bonita. Es práctica sucia. Y la herramienta que te salva la vida se llama Plum. Sí, Plum. La plomada. La que te dice si lo que has levantado está vertical o te lo estás inventando sobre la marcha.

Resumen rápido (lectores con prisa)

Qué es: Plum es un guardián operativo que convierte decisiones (humanas o de LLM) en artefactos rastreables ligados a commits.

Cuándo usarlo: Cuando usas agentes o LLMs para tomar decisiones que afectan código, specs o tests.

Por qué importa: Evita que las decisiones queden atrapadas en chats y que el repositorio pierda la memoria de intención.

Cómo funciona (resumen): Hooks de Git + extracción de traces + bloqueo de commits hasta aprobación + sincronización spec↔tests↔código.

Por qué hay que preocuparse ahora

– Porque los LLMs generan código a ritmo industrial.

– Porque cambios urgentes o hotfixes se meten directo al trunk.

– Porque las decisiones que importan quedan atrapadas en chats —los famosos traces— y se evaporan al cerrar la sesión.

– Porque las especificaciones se quedan en Markdown como si fueran altares estáticos, sin reflejar lo que el código realmente hace.

La consecuencia: código que pasa tests pero no cumple intención. Tests que validan outputs, no contratos. Specs que no son contrato sino historia. Y equipos que no pueden responder cuando algo explota en producción.

Cómo funciona Plum —sin poesía— pero con sentido

1) plum init

– Crea .plum y .plumignore.

– Te pide dónde están tus specs (Markdown) y tus tests (por ahora Pytest).

– Añade hooks a Git: el commit se convierte en punto de control, no en trámite.

2) Haces código con un agente

– El agente toma decisiones en el chat. Tú las apruebas o las ajustas.

– Al intentar git commit, Plum hace su trabajo: compara diffs desde el último commit y escanea los traces del agente.

3) Plum extrae decisiones

– Deduplica (sí, imperfecto; más abajo explico por qué).

– Te presenta: “estas son las decisiones que tomaste desde el último commit. ¿Las apruebas?”.

– Si hay decisiones pendientes, el commit falla. Sí, falla a propósito. Tú apruebas o corriges.

4) Aprobadas → actualizaciones y registro

– Aprobadas => Plum actualiza la spec (Markdown) y genera un registro .jsonl con la decisión, la autoría (humano o LLM), rama, timestamps y vínculo al diff.

5) Ejecutas plum sync

– Plum te muestra las brechas entre spec, tests y código: requisitos sin tests, tests sin caso claro, etc.

Por qué no puede ser “una skill” del agente

Porque una skill es una sugerencia dentro del agente. Y las sugerencias se ignoran cuando hay prisa. Si quieres gobernanza necesitas un checkpoint externo e innegociable. Si el commit no falla, la herramienta es una opción más que nadie usa. Plum falla commits a propósito para forzar el acto reflexivo: “aprobación humana o nada”.

La plomada no pinta paredes. Te evita derrumbes.

Qué hay dentro del archivo JSONL y por qué importa

El .jsonl no es un “log más”. Es un registro de intención con metadatos para auditoría.

Ejemplo de entrada:

– question: “¿Batchear updates de spec o aplicar por decisión?”

– decision: “Batch spec updates across all decisions”

– approved_by: user@example.com

– proposed_by: LLM (o human)

– branch: feature/x

– diff_link: git://…

– timestamps: created, approved, synced

Ese registro responde a: quién decidió, qué decidió, por qué y cuándo. Lo que todo equipo serio debería exigir.

Limitaciones reales (no las bonitas)

• Pytest-only por ahora. Si usas otro runner, el análisis de cobertura falla. Esto es temporal, pero real.
• Backfill: Plum funciona mejor si la spec va adelante del código. Analizar un monolito legacy y generar spec desde cero es una tarea distinta.
• Decision deduping es fuzzy. Identificar “la misma decisión” entre conversaciones humanas y LLMs no es trivial. Depende del repo, del dominio y de tu tolerancia.
• Ruido de interrupción. Si generas cinco decisiones por un hotfix, te puede cortar el flow. Por eso Plum necesita umbrales de interrupción configurables.
• Rollbacks automáticos: si rechazas una decisión en la CLI, que se revierta el cambio en el código todavía requiere flujo claro entre agente y control de versiones. No siempre está resuelto. Lo ideal: rechazo en el CLI que abre un “rework” en el agente con rollback automático; hoy es work-in-progress.

Diseño de umbrales —el arte de no volver loco al dev

Velocidad es vida. Interrupciones matan. Así que Plum permite (y debe permitir) configurar tolerancias:

• Modo “dangerously approve all” para prototipos.
• Modo “auditable strict” para banking, salud, compliance.
• Filtros por carpeta o tipo de archivo (ej.: cambios en README no generan decisiones).
• Severidad: solo interrumpir cuando la decisión sea contradictoria con reglas previas o afecte invariantes del sistema.
• Timebox: decisiones ligeras se acumulan y se presentan en lote, las críticas se presentan inmediatamente.

Esto es clave: la herramienta debe ser lo suficientemente simple para que cada dev la mantenga en su cabeza. Si no, la ignorarán.

DSPy y la búsqueda del determinismo

No me gustan las soluciones que dependen sólo de LLMs para validar la validez de una regla. Cuando puedes usar código —tests, parsers, análisis sintáctico— úsalo. Donde no puedas, estructura las llamadas a LLMs. DSPy ayuda: define inputs/outputs tipados para las llamadas a modelos, reduce alucinaciones y permite testear las respuestas.

Ejemplo práctico:

• Deducción de decisión = tarea rápida → GPT-OSS (rápido).
• Parse semántico de spec = tarea precisa → modelo con DSPy que devuelva JSON estricto.
• Cuando falla la determinación, vuelve al humano.

Por qué esto cambia la revisión de código

Hoy revisas sintaxis y estilo. Mañana, sin estas herramientas, revisarás humo. Con Plum revisas intención. Ves “por qué existe esta función” y no sólo “si el PR es legible”. Es code review con memoria. Y esa memoria evita que los agentes te reproduzcan antiguas prohibiciones por olvido de contexto.

Checklist mínimo para empezar (15 minutos)

1. Pip install plum-dev
2. plumb init (apunta al folder de specs y a tu carpeta de tests)
3. Añade .plumignore para evitar ruido (README, docs, etc.)
4. Ajusta umbrales: prototipo vs production.
5. Corre un hotfix con agente y haz commit — observa el commit-fail, aprueba decisiones.
6. Ejecuta plum sync y revisa cobertura spec↔tests↔código.
7. Guarda el .jsonl en la rama y pásalo por review.

Casos de uso concretos

• Startups: modo “dangerously approve” para protos, switch a strict cuando tienes usuarios reales.
• Fintech / Salud: strict desde el primer día, cada micro-decision auditada.
• Open Source: Plum ayuda a traducir PRs dispersos en decisiones rastreables y aprobadas.

Metáfora breve

Tu repo es un edificio. Los agentes son una cuadrilla hiperactiva que puede añadir habitaciones a velocidad absurda. La spec es el plano. Si no actualizas planos y firmas cambios, un día entras y la escalera está en el baño. Plum es la plomada: no te dice cómo pintar, te dice si la pared está derecha.

La urgencia práctica

Si ya usas agentes y no capturas decisiones, estás construyendo un legado que nadie asumirá. La deuda técnica no es solo trabajo: es riesgo legal, fiscal y reputacional. La gobernanza no es un lujo, es supervivencia.

¿Quieres empezar ahora?

Pruébalo: pip install plum-dev y corre plum init en una rama de feature.

Si quieres que te lo haga más fácil, te doy 3 cosas ahora mismo:

• Un template de .jsonl para registrar decisiones.
• Un flujo de PR (CI) que bloquea merges hasta sync exitoso.
• Un checklist para integrar Plum en 15 minutos.

Respóndeme este mensaje y te lo envío. O instala plum-dev y me cuentas qué encuentras en tu primer commit con agente. Te prometo que descubrirás decisiones que no sabías que habías tomado.

Si el artículo y su enfoque encajan con tus flujos de automatización, considera explorar más en Dominicode Labs como continuación lógica a la integración de herramientas y procesos en equipos técnicos.

FAQ

• ¿Qué hace exactamente Plum cuando instalo y lo configuro?
• ¿Plum genera código o modifica mi base de código automático?
• ¿Qué pasa si no quiero que ciertos cambios sean bloqueados?
• ¿Plum soporta todos los frameworks de tests?
• ¿Cómo se ve un registro de decisión y qué metadatos incluye?
• ¿Qué ocurre si Plum detecta decisiones conflictivas?
• ¿Plum puede integrarse en CI para bloquear merges?