uscha.dev
los specs compilan · el código se regenera · un humano cura

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.

kit v2.17.0 licencia MIT Windows · macOS · Linux Python 3.8+ · cero deps 9 skills 7 agentes · 2 ejercitados, 5 verificados por ubicación
el problema

El agente dice que terminó. ¿Quién lo contradice?

Un agente te va a decir que los tests pasan. Te va a decir que la feature está terminada. Suele tener razón — y cuando no la tiene, te enterás en producción.
los dos paradigmas

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.

Loop abierto
El agente decide el recorrido
  • investiga
  • modifica código
  • ejecuta tests
  • revisa el resultado
  • ¿resuelto?
  • termina — o vuelve a intentar
Grafo medido
Vos definís los caminos posibles
  • 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.

El loop abierto te da un agente que cree que terminó. Uscha te da un agente que no puede terminar hasta que la evidencia lo habilite y un humano lo apruebe.

Leé el ensayo completo: por qué existe uscha →

La regla que ordena todo

Los gates que leen HECHOS bloquean; los que ADIVINAN sobre prosa, avisan.

la columna vertebral

Cinco reglas. Nada más — y nada menos.

01

No hay código sin SPEC + ACCEPTANCE

Antes de construir, existe qué se construye y cómo se sabe que está bien.

02

La verdad vive en archivos versionados

No en el chat. SPEC.md, ADR, ACCEPTANCE.md, QA-LEDGER.json — todo en el repo.

03

El humano siempre aprueba el merge

El pipeline frena en el gate de merge. Siempre. Sin excepción.

04

Los tests deben asertar

El gate nunca se debilita para que pase. Un test que no aserta no es un test.

05

Migraciones ancladas con golden

El comportamiento viejo se captura mecánicamente antes de tocarlo. El agente jamás authorea el .approved.

el sendero

De la idea a producción, con compuertas en el camino

idea→ discovery→ spec→ adr / constitution→ build→ qa loop→ verify→ gate humano→ producción
compuerta medida aprobación humana
rigor ganado

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.

fast-path

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.

spec-drift

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.

el kit

Nueve skills que cubren el ciclo completo

Del interrogatorio inicial al dashboard de estado. Cada skill hace una cosa; el ledger las une.

/uscha-discovery

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.

/uscha-adr-refine

Entrevistar, después destilar: la misma entrevista aplicada a una feature ya conocida. No es un generador — es un interrogador.

/uscha-devloop

El orquestador de construcción + QA: ciclo disciplinado, cada paso en el ledger, y freno duro en el gate humano del merge.

/uscha-characterize

Congelar el comportamiento actual como verdad de campo: la suite golden — el único artefacto que el agente no puede authorear.

/uscha-reverse-discovery

El inverso de discovery, para brownfield: no se inventa nada — se extraen hechos del sistema existente, como mapa + golden.

/uscha-rubric

El ACCEPTANCE de lo no-testeable: puntúa el cambio contra un RUBRIC.md versionado. Advisory por default.

/uscha-mirador

Estado real a vista de pájaro: readiness, sub-scores, fases, invariantes y loops de QA. La skill cablea — no calcula.

/uscha-sysdoc

El deck de sistema en dos pistas — comercial y técnica — con métricas reales del ledger. Reporte opcional, a pedido.

/uscha-status

El statusline a demanda: readout de progreso de una línea, para superficies donde el statusline no se ve.

la biblioteca

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.

tesis

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.

ensayo

Por qué existe uscha

Loop abierto vs. grafo medido: quién contesta las compuertas, y por qué el loop se enjaula en vez de eliminarse.

diagramas

Có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 interactivo

Mapa 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 html

Curso 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 html

Documentació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és

El 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 real

Field 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.

los números del motor

Lo medido le gana a lo narrado — también acá

67
subcomandos del motor
11
stacks de lenguaje
9
skills en el kit
0
dependencias runtime
100%
stdlib de Python
8/12
arquetipos se regeneran — el bench (medido en septiembre de 2026; cuatro compiladores ciegos — Haiku, Sonnet, Opus y OpenAI Codex gpt-5.5)

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.

Nota de campo · caso real 001
"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.