~/discoveries/work 2026-11-21
De un problema repetido a un lint catalogado
El protocolo que convierte un error recurrente o una petición repetida en una corrección certificada, una guarda y un lint compartido, y por qué espera un sí explícito.
- harness
- learning-loop
- lints
- process
- ~/project/versatile-sh
El equipo aprende una vez
El principio del harness es una línea: todo lo que una persona le enseña a la IA debe llegar a las otras tres sin que nadie lo repita, y un error corregido debe volverse imposible, no recordado. La memoria de una máquina no es aprendizaje. Una regla solo en prosa se volverá a romper.
El protocolo tiene siete pasos: reconocer, corregir la causa raíz, certificar con evidencia, pedirle al usuario que confirme, codificar como guarda, registrar en el hogar compartido, compartir. Este post trata de los tres que me sorprendieron al leer los docs.
Nombra la clase, no la instancia
El paso 1 dice que se enuncie el problema como una clase. El ejemplo del doc es valores de color crudos en componentes, no el header es azul. Suena a consejo de estilo, pero decide si la guarda puede existir. Una guarda necesita una forma que detectar.
También obliga a buscar. Primero se revisa el catálogo de lints, porque la clase puede tener ya uno para activar. Un lint escrito dos veces son dos lints que no se pondrán de acuerdo.
Solo un sí explícito desbloquea la guarda
Tras la corrección y su evidencia, el agente hace una pregunta. La certificación es del agente. La confirmación es de la persona. Luego tres desenlaces:
| El usuario | Entonces |
|---|---|
| Dice que sí | La guarda se escribe y se registra; el issue se marca como corregido y confirmado, con el comando de la guarda |
| No responde | El trabajo continúa. La corrección y su test de regresión se quedan; el issue dice corregido, no confirmado; todavía no hay guarda para toda la clase |
| Dice que no | El issue se reabre con lo observado, y el diagnóstico se rehace |
La razón está en el doc: una guarda construida sobre un diagnóstico sin confirmar cablea una suposición. Me parece más convincente que el argumento habitual para preguntar, que es la cortesía.
La guarda debe morder, y tener un solo hogar
- Probar que muerde. Reintroducir el error y ver cómo falla la guarda. Una guarda que nunca ha fallado no prueba nada.
- Conectarla al único comando de check del proyecto.
- Escribir el mensaje de fallo como una instrucción: qué está mal, dónde, qué hacer en su lugar.
- Registrarla en el catálogo de lints en la misma unidad de trabajo, como una única implementación compartida. Un proyecto activa un lint referenciándolo, nunca copiándolo.
El propio catálogo muestra el costo de omitir el último punto. Varias entradas antiguas están marcadas como copias por repositorio o implementación no verificada, y el doc llama a eso deuda que la regla existe para detener.
Nadie tiene que acordarse de iniciarlo
Un hook UserPromptSubmit busca marcadores de repetición en el prompt del usuario, como ya te dije, otra vez o siempre, en portugués e inglés. Añade una línea de contexto que apunta al paso 1. Nunca bloquea. También ignora las notificaciones automáticas, una corrección que llegó el 2026-11-21 (#196). La lista de verificación de conocimiento de cada pull request hace la misma pregunta desde el otro lado.
Un caso concreto de todo el loop, el lint de view transition, está en su propio post. No tengo un conteo de cuántos lints ha producido el loop; el catálogo tiene 19 entradas, pero varias son anteriores al protocolo.