Las specs son el código fuente.
El código es un artefacto de build.
El paquete de specs es el fuente; el LLM es el compilador — convierte el spec en código, y el código pasa a ser un artefacto de build regenerable. Reverse discovery corre al revés: del código existente de vuelta a specs, con un humano juzgando cada afirmación antes de que cuente. La tesis está medida, no prometida: sistemas acotados se regeneran al mismo comportamiento bajo una prueba que los compiladores nunca vieron, y el número se publica con su techo. El mecanismo completo, con los términos definidos, está un click más abajo.
El agente ejecuta · el método gobierna · la evidencia decide · el humano aprueba.
$ npx --yes @andresmassello/uscha@latest install --target claude
Targets: claude · codex · cursor · copilot · gemini · cline · pi — o --target all. Alcance honesto: Claude Code y Codex están ejercitados contra un agente real; los otros cinco se verifican solo por ubicación + relectura.
El agente dice que terminó. ¿Quién lo contradice?
Loop abierto vs. grafo medido
Hay dos formas de poner un agente a trabajar sobre código. En el loop abierto, el agente decide el recorrido y se pregunta a sí mismo si terminó — nadie afuera lo contradice. En el grafo medido, el humano define los caminos posibles y cada compuerta la contesta evidencia medida, no el agente. Es la misma disciplina que, un nivel arriba, deja que el código mismo se vuelva descartable — el diamante.
- investiga
- modifica código
- ejecuta tests
- revisa el resultado
- ¿resuelto?
- termina — o vuelve a intentar
- reproducir el bug
- ¿lo reproduce?
- hallar causa · intentar fix
- ¿pasan los tests?
- revisión
- ¿aprobado por un humano?
Uscha es ese grafo medido, con dos particularidades: cada compuerta la contesta un artefacto determinista y auditable — el ledger, los gates, la cobertura, el golden — y el loop no desaparece: se enjaula dentro de un nodo de convergencia acotado que o converge o escala a un humano.
Leé el ensayo completo: por qué existe uscha →
Los gates que leen HECHOS bloquean; los que ADIVINAN sobre prosa, avisan.
Cinco reglas. Nada más — y nada menos.
No hay código sin SPEC + ACCEPTANCE
Antes de construir, existe qué se construye y cómo se sabe que está bien.
La verdad vive en archivos versionados
No en el chat. SPEC.md, ADR, ACCEPTANCE.md, QA-LEDGER.json — todo en el repo.
El humano siempre aprueba el merge
El pipeline frena en el gate de merge. Siempre. Sin excepción.
Los tests deben asertar
El gate nunca se debilita para que pase. Un test que no aserta no es un test.
Migraciones ancladas con golden
El comportamiento viejo se captura mecánicamente antes de tocarlo. El agente jamás authorea el .approved.
De la idea a producción, con compuertas en el camino
El piso de ceremonia no es plano
"Rigor donde las stakes lo justifican" solo se sostiene si vale el inverso también. Un fix de una línea y una migración de schema pagaban el mismo costo de entrada. Dos mecanismos medidos lo corrigen — ninguno confía en la palabra del agente.
Los cambios chicos comprobables saltean la ceremonia
El motor mide el diff real — archivos, líneas, paths protegidos — y solo un cambio comprobablemente chico toma el atajo. Nada auto-reportado: decide el motor, no el agente. El rigor es un trinquete de una sola vía — siempre podés pedir más, nunca menos. La aprobación y los tests que asertan no se saltean jamás.
Specs viejos, hechos visibles
Los specs se pudren en silencio cuando el código se mueve y nadie los toca. uscha lo marca mecánicamente desde las fechas de git. Es consultivo — un disparador de conversación, nunca un build bloqueado.
Nueve skills que cubren el ciclo completo
Del interrogatorio inicial al dashboard de estado. Cada skill hace una cosa; el ledger las une.
De la idea pelada al paquete de spec: la skill interroga hasta que exista una forma compartida del sistema, y escribe los documentos sobre la marcha.
Entrevistar, después destilar: la misma entrevista aplicada a una feature ya conocida. No es un generador — es un interrogador.
El orquestador de construcción + QA: ciclo disciplinado, cada paso en el ledger, y freno duro en el gate humano del merge.
Congelar el comportamiento actual como verdad de campo: la suite golden — el único artefacto que el agente no puede authorear.
El inverso de discovery, para brownfield: no se inventa nada — se extraen hechos del sistema existente, como mapa + golden.
El ACCEPTANCE de lo no-testeable: puntúa el cambio contra un RUBRIC.md versionado. Advisory por default.
Estado real a vista de pájaro: readiness, sub-scores, fases, invariantes y loops de QA. La skill cablea — no calcula.
El deck de sistema en dos pistas — comercial y técnica — con métricas reales del ledger. Reporte opcional, a pedido.
El statusline a demanda: readout de progreso de una línea, para superficies donde el statusline no se ve.
Para profundizar: la documentación completa
Todo lo de abajo se genera desde el mismo repo del que sale el kit — las docs y el código viajan juntos.
El diamante — las specs son el código fuente
La tesis de fondo: el LLM como compilador, reverse discovery como decompilador, el código como artefacto de build — con tabla truth-pass separando lo real de lo que sigue siendo visión.
ensayoPor qué existe uscha
Loop abierto vs. grafo medido: quién contesta las compuertas, y por qué el loop se enjaula en vez de eliminarse.
diagramasCómo funciona
Cuatro diagramas: discovery greenfield, reverse discovery brownfield, el mecanismo de curación donde un único veredicto humano es el único juicio del loop, y la ida que alimentan (compilar, certificar, round-trip).
diagrama interactivoMapa de componentes
Todas las piezas del kit en una página, de izquierda a derecha: el método gobierna, la herramienta ejecuta, la evidencia decide, el humano aprueba.
curso htmlCurso de 2 días para developers
De cero a producción: día 1 construye una feature nueva, día 2 migra un sistema existente — discovery, characterize, reverse-discovery.
referencia htmlDocumentación completa
El método completo en un solo lugar: las reglas, las fases, cada skill, los gates y el ledger — el doc grande.
paper html · pdf · inglésEl paper
El tratamiento formal: una metodología fact-gated y tool-agnóstica para desarrollo spec-driven con agentes de código LLM.
nota de campo proyecto realField note 001 — migración de tesorería
Un proyecto real, anonimizado: 19 checkboxes declarados, 16 aceptados por el motor — y las cinco veces que el grafo medido contradijo un "terminado" aparente.
Lo medido le gana a lo narrado — también acá
El motor es qa_ledger.py: Python puro, sin pip installs. Ingesta evidencia de
maven, gradle, ant, python, node, go, rust, dotnet, cpp, swift y flutter, y la registra en
QA-LEDGER.json — un ledger determinístico que anota lo que se midió, nunca lo que se afirmó.
Cada veredicto del ledger está atado a un criterio nombrado — y, cuando lo juzgó un humano, a la
persona que lo firmó. Eso sale del propio ledger, de bench-curate --human para los
artefactos compilados del bench Diamond, y de las marcas origin: agent que registran
qué ítems de la especificación propuso el agente y cuáles decidió el humano.
La evidencia de tests tiene testigo, no solo lectura: test-run ejecuta el comando de tests
que declaró tu proyecto, registra la corrida, y los gates solo aceptan los reportes que esa corrida
escribió. Un reporte escrito, copiado o editado por otra vía no es evidencia, y una revisión de QA
cuenta solo si se registró (review-start) sobre el árbol exacto que vio. Lo que sigue
siendo confianza es el propio comando declarado —una línea de config que revisa una persona— y el
motor no puede probar que una revisión se hizo, solo sobre qué árbol dice haberse hecho.
Los actos humanos siguen siendo humanos. Levantar una escalación, o confirmar que un hallazgo bloqueante puede esperar, exige declarar un nombre y un motivo,
y esos comandos se niegan a correr dentro del shell de Claude Code; ahí, además, un hook mantiene el
pull request en draft mientras el gate está en rojo. Los dos límites están a la vista: un nombre
declarado no prueba identidad, un agente puede borrar la marca, otros harnesses no exponen ninguna, y
el hook lee la llamada como texto, así que gh api o un navegador pasan igual. El único acto
humano autenticado es el "ready for review" o el merge en la propia forja.
Los diseños con estado se verifican antes de construirse. Desde el ADR que el proyecto elige, cada diseño
deja escrito si necesita un modelo TLA+; model-check --run corre TLC desde un jar fijado por hash y
registra el veredicto, y sin Java los modelos quedan UNMEASURED, nunca aprobados. Es advisory salvo que el
proyecto declare un gate. Un modelo en verde significa que TLC no encontró violaciones del modelo dentro de
sus límites; el test rojo que reproduce cada contraejemplo es el único vínculo con el código.
El esfuerzo de revisión sigue al cambio. Un proyecto que declara review_tiers asigna a cada
ruta una revisión quick, standard o deep; el motor se queda con el tier más alto que alcanzó cualquier archivo
del cambio, le asigna a cada herramienta de revisión su alcance, y un fix se revisa de nuevo sobre su diff con
cada herramienta cuyo paso limpio quedó viejo. Bajar un tier es un acto humano. El diseño se verificó antes con
un modelo, y el modelo obligó a un cambio: la regla tal como se escribió primero dejaba pasar un hallazgo
conocido aun con un agente honesto.
"Check" es una pregunta. El agente respondió con un commit.
Un humano pidió "revisá" unos errores de QA remoto. El agente diagnosticó bien — y en el mismo turno, sin mostrar el diagnóstico ni esperar respuesta, anunció "diseño cerrado", editó tests y código de producción, y corrió el build. Entre la pregunta y el código modificado: cero puntos de decisión humana. La ejecución fue competente; la falla fue de gobernanza. Ese es exactamente el agujero que Uscha existe para cerrar.