~/discoveries/work 2026-11-20 · published 2026-11-21
Una compuerta que el modelo pasa haciendo el trabajo
Un hook PreToolUse retiene gh pr create hasta que se registra el checklist de conocimiento de la sesión. La compuerta no le pregunta a ninguna persona; le pide al modelo que termine el trabajo que se saltó.
- harness
- hooks
- pull-requests
- python
- ~/project/versatile-sh
La falla que ataca
Las sesiones corren por repositorio. Cuando una sesión cierra un pull request en un proyecto, lo que aprendió suele quedarse en el pull request o en ninguna parte. Puede que el README se actualice; el registro en la base de conocimiento, una regla que surgió, una nota de que cambió la forma de trabajar, a menudo no.
La respuesta del equipo es un checklist de cinco líneas: comportamiento visible al usuario (README y docs), registros del proyecto, reglas y lints, la forma de trabajar, y una última que pregunta si algo ajeno a Versatile se filtró en los docs. Cada línea termina con un enlace a un pull request, `in this PR` o `n/a` con una razón. Un checklist que nadie está obligado a leer es decoración, así que lo hace cumplir un hook.
Qué hace el hook
`hooks/pr-gate.py` corre antes de cada llamada a Bash. No hace nada salvo que el comando sea un `gh pr create` que realmente se ejecuta como comando (tokeniza la línea de shell, sigue `cd` y lee `--repo` y `--head`). Luego verifica si el repositorio pertenece a la organización y si existe un marcador para esa rama.
Sin marcador: la llamada se deniega, con una razón que es una lista de tareas para el modelo. Nombra los pasos del checklist, el comando exacto de `bin/pr-ready` para registrarlos y la sección del doc que lo explica.
bin/pr-ready --readme "in this PR" --records <url> \
--knowledge "n/a: no rule or lint emerged" \
--way "n/a: unchanged" --versatile-only
bin/pr-ready --nothing "a typo fix; nothing was learned or decided"La compuerta no necesita la aprobación de una persona. El modelo la satisface haciendo el checklist. Lo que la persona recibe es el último paso: el mensaje del hook también le dice al modelo que diga en el chat qué se actualizó, con enlaces, o por qué no se actualizó nada.
Decisiones de diseño que defendería
- Falla abierta. Cualquier excepción dentro del hook deja pasar el comando. Una compuerta rota que bloquea todos los pull requests acabaría eliminada.
- Es una retención, no un candado. El registro expira después de un día, y una variable de entorno o un archivo en el directorio de configuración la apaga.
- No se aplica a los propios repositorios del harness. Sus pull requests son la actualización de conocimiento.
- La salida para una sesión realmente vacía existe (`--nothing`) pero exige una cadena con la razón. Escribir la razón es la fricción.
Una compuerta simbólica puede satisfacerse simbólicamente. El modelo puede escribir n/a en cada línea. Lo que lo frena es la regla final: hay que avisarle al piloto en el chat, así que un n/a perezoso es visible para un humano.
Lo que no medí
No tengo un conteo de cuántas veces la compuerta retuvo un pull request ni de cuántas respuestas fueron n/a. El hook aterrizó el 2026-11-20, y la regla del doc sobre el checklist se revisó el mismo día (#166 hizo que la compuerta citara el doc que una skill personal del mismo nombre no traería). Mientras no haya un log de retenciones, la afirmación de que la compuerta mejora los registros es una hipótesis. Lo primero que miraría es la proporción de respuestas n/a frente a enlaces.