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
Tres flujos en una imagen cada uno: discovery greenfield, reverse discovery brownfield, y el mecanismo de curación donde un único veredicto humano es el único juicio del loop.
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.
"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.