Las nueve skills del método.

Qué es. El humano trae la idea, las restricciones y el material de referencia; la skill trae la forma: interroga hasta que exista una forma compartida del sistema y escribe los documentos sobre la marcha — no le pide al humano que diseñe el sistema por ella.

Cuándo. "discovery", "modelá esto desde una idea", "solo tengo la idea, no sé el cómo todavía". Cuándo NO: feature con forma clara → uscha-adr-refine; sistema existente a migrar → uscha-reverse-discovery.

Principios no negociables

• Una pregunta por vez, cada una CON respuesta recomendada. La inversión que hace funcionar el discovery: la skill propone (entidades, endpoints, arquitectura, un default), el humano confirma o corrige. Jamás una lista de 20 preguntas.
• Explorar antes de preguntar. Si un doc de referencia, el codebase o un CONTEXT.md/docs/adr/ responde la pregunta, se lee primero.
• Proponer la forma. Entidades núcleo, superficie de operaciones y 2–3 opciones de arquitectura con trade-offs; el árbol de diseño se camina rama por rama.
• Interrogar, no acordar. Contradicciones, términos difusos, modos de falla ausentes. Un discovery donde la skill acordó con todo, falló.
• Archivos lazy e inline. Un archivo se crea recién cuando hay algo real que escribir y se actualiza cuando la decisión cristaliza — nunca batch al final.

La agenda de interrogatorio (en orden; se saltea lo que las referencias ya responden)

1. Propósito / valor / por qué ahora — qué trabajo elimina, qué cuesta no hacerlo.
2. Modelo de dominio — la skill propone entidades núcleo y relaciones.
3. Superficie de operaciones / API — endpoints, contratos, idempotencia, códigos.
4. Decisiones grandes (→ ADR) — 2–3 opciones con trade-offs y default recomendado.
5. Comportamiento y casos sucios — happy path y DESPUÉS fallas, reintentos, estados parciales, concurrencia, qué NO debe pasar.
6. Restricciones inviolables (→ CONSTITUTION.md) — un invariante por línea, CWE donde mapee; alimentan el severity gate y una violación es BLOCKER, nunca trade-off.
7. Out of scope — límites explícitos con referencias forward.
8. Acceptance / DoD — criterios concretos y chequeables + métricas.
9. Quality bar (→ config, 1.17.0) — "¿qué nivel de calidad BASTA y qué es negociable?". Lo declarado va a uscha.config.json y lee como requerimiento (config); lo no declarado queda como default del kit (opinión) y así se etiqueta. Declarar es commitear el config.
10. Riesgos y dependencias — por cada riesgo de incertidumbre ALTA (1.19.0): "¿amerita un spike time-boxed?". El spike corre en rama spike/* y su único output legítimo es un ADR con lecciones — phase --require pr-ready rechaza esa rama, estilo INV-GOLDEN-01.

Artefactos (lazy, a medida que cristaliza)

Qué es. La misma entrevista aplicada a una feature CONOCIDA: la forma ya está clara, falta precisión. No es un generador: es un interrogador que destila. El valor está en las preguntas, no en acordar. Es la contraparte front-half de uscha-devloop.

Cuándo. "refine the ADR", "let's spec this before coding", "ayudame a definir esto antes de desarrollar".

Principios no negociables

• Interrogar, no validar — superficializar lo implícito y encontrar los agujeros.
• Converger, no quedarse sin preguntas — la entrevista termina por criterio OBJETIVO, no cuando el humano parece cansado. La misma disciplina del "converge, don't chase zero" de uscha-devloop, en el frente.
• Cero artefactos antes de converger — ante un "escribilo ya", primero se nombran los gaps abiertos.
• Un tema por vez — lotes enfocados, reflejando "Decidido: … / Sigue abierto: …" antes de avanzar.
• Los "decidilo vos" se registran — ante deferencia en decisión consecuente se devuelve el trade-off UNA vez; si insiste, queda como supuesto explícito en el ADR, jamás default silencioso.

Fase A — la entrevista (agenda)

1. Problema y por qué ahora — si el "por qué ahora" no tiene respuesta, la prioridad es sospechosa.
2. Decisiones implícitas — sync/async, storage, protocolo, idempotencia, límites transaccionales, quién es dueño del estado; cada una con alternativa considerada.
3. Comportamiento — happy path y luego los casos SUCIOS: timeouts, reintentos y backoff, 4xx vs 5xx, concurrencia, estados parciales/terminales. Una feature sin su comportamiento de falla está a medio especificar.
4. Restricciones inviolables (→ CONSTITUTION.md) — un ADR jamás puede contradecir la CONSTITUTION: si una decisión lo haría, se escala, no se registra.
5. Out of scope — lo que excluís es tan importante como lo que incluís.
6. DoD + métricas de éxito — cada ítem verificable, no una sensación.
7. Dependencias — qué specs/sistemas/credenciales tienen que existir antes.

Fase B — destilar (solo tras converger)

• Un ADR por decisión que valga registrar, formato fijo: Estado · Contexto (opciones A/B/C) · Decisión · Razones · Consecuencias (+/−) · Implementation Plan · Verification. Numeración continúa desde el ADR más alto. Las decisiones negativas cuentan: "lo que NO vamos a usar y por qué" es un ADR válido.
• ACCEPTANCE.md en el root (o el path del config): Definición de hecho · Cómo medimos éxito · Out of scope · Decisiones registradas. Es el archivo que el readiness mide.
• Si surgió un invariante nuevo, va a CONSTITUTION.md — nunca dejarlo en un ADR donde después pueda "negociarse".

Anti-patrones explícitos

• Generar un ADR desde un pedido de una línea sin entrevistar.
• Aceptar "hacelo como quieras" sin registrar el supuesto.
• Escribir un criterio no chequeable ("que funcione bien").
• Emitir artefactos antes de las condiciones de convergencia.

Qué es. Un ciclo disciplinado de desarrollo + QA sobre uno o más repos, con cada paso en un ledger determinístico (QA-LEDGER.json) y freno duro en el merge gate humano. Todas las métricas salen del ledger — jamás estimar de memoria. Dos niveles: registros medidos (snapshots, ingest-gate, log-gate — parseados de artefactos reales; pueden bloquear) y conteos auto-reportados (log-step — narración para la retrospectiva). Un rojo medido siempre pisa un verde narrado.

Para quién / cuándo NO. Un operador llevando UN cambio no trivial o con riesgo. NO para trabajo trivial — un fix de un archivo corre build+test y se saltea discovery/ADR/uscha-sysdoc (tabla de perfiles del playbook).

Principios no negociables

• Convergé, no persigas el cero. Solo bloquean findings ≥ severity gate (default BLOCKER/CRITICAL/HIGH); el resto va a ISSUES-DEFERRED.md. Pulir Medium/Low para siempre es el modo de falla que esta skill previene.
• Los tests son guardarraíl, no final. El test command corre tras CADA pase que cambió código; suite roja frena el loop.
• Generar tests no es correr tests. /improve test corre UNA vez al final contra código estabilizado — jamás dentro del loop.
• Freno en el merge. La skill crea el PR y confirma CI; NO mergea.
• Markdown trackeado — pedir la versión actual antes de modificar.
• El golden no se authorea. .approved = verdad de campo aprobada por un HUMANO; la skill emite .received y frena (hook PreToolUse — INV-GOLDEN-01).

Las fases

1. Setup — init --config uscha.config.json; cada repo con su type (maven·flutter·python·node·go·rust·dotnet·cpp·gradle·swift). Perfil E: instalar además el hook del golden + .gitattributes.
2. Fase 0 — Plan (ADR-first). CONSTITUTION.md se lee PRIMERO. Input: ADR set + ACCEPTANCE.md. Sin criterios de acceptance → frenar y correr adr-refine. El loop apunta al plan, no a "cero issues".
3. Fase 1 — Coverage gate → caracterización condicional. snapshot --phase pre + check-coverage. Bajo el umbral → tests de contrato EN EL BORDE (no internals), revisados por el humano. Migración → golden ANTES de tocar nada; sin golden aprobado no hay build.
4. Fase 2 — Build. Commits convencionales por paso lógico. Disciplina ADR: consultar antes de tocar área gobernada; triggers proactivos de ADR nuevo; linkear código↔ADR; jamás editar la SPEC/ADR para que la implementación parezca correcta.
5. Fase 2b — Simplicity gate ("Reduce"). simplicity-check sobre el diff; OVERBUILT (exit 1) es BLOCKER: recortar y re-correr. Los tests quedan FUERA del presupuesto (1.11.0). Se persiste con log-gate --kind simplicity.
6. Fase 2c — Waste gate ("Reuse-first", 1.26.0). waste-check: detección determinística de clones Type-1/2 del diff contra el REPOSITORIO — la duplicación que simplicity-check no puede ver (puntúa el diff aislado). Cada flag nombra el file:line a reusar. Advisory por default; gatea solo con --gate o defaults.waste.gate. Raíz: muda Lean (Poppendieck) + el +81% de duplicación que midió GitClear.
7. Fase 3 — QA loop (por repo). Tools de qa_tools_order (code-review → judgment-day → improve); un pase de todas = un ciclo. Tras cada pase: fixes ≥ gate, tests, log-step. En cada pase que cambió código: gate-check (¿debilitó el aparato? ¿agregó un secreto? — 1.12.0) y golden-diff en migración, persistidos con log-gate. Find Bugs Once (1.16.0): con --fixed > 0, correr regression-check — cierre sin línea nueva de test = NARRATED (el test que falla va ANTES del fix). El static gate se ingiere con ingest-gate (severidades normalizadas, fixed real por diff de IDs). Cierre de ciclo: converged + oscillation.
8. Fase 4 — Integración. La capa cross-repo con todos los repos montados, logueada bajo --repo integration. Verde por-repo no implica costuras verdes.
9. Fase 5 — Verify. Recién ahora se escribe la cobertura fina; suite completa verde, snapshot --phase post.
10. Fase 5b — Rebuild test (opcional, perfil C+/E). ¿La SPEC alcanza para regenerar el sistema? Un test que pasaba y falla en el regenerado = comportamiento que la SPEC dejó implícito. La divergencia es gap de spec, no bug de código.
11. Fase 6 — PR. phase --require pr-ready POR REPO antes de abrir: estado COMPUTADO del ledger, jamás declarado; exit 1 lista los hechos que faltan. Rama spike/* jamás pasa (1.19.0). PR, CI verde, STOP — el humano mergea.
12. Fase 7 — Smoke list. Checklist manual concreto (rutas reales, endpoints, flujos de device).
13. Fase 8 — Docs + retrospectiva. summary (+ --json para sys-doc; incluye el first-time yield (FTY, 1.27.0): % de repos que pasaron QA en el primer ciclo, sin rework ni escalación — métrica Lean informativa, jamás gatea) y el readiness KPI tras CUALQUIER tarea: acceptance MEDIDA 30 · static 20 · adr 15 · coverage 15 · convergencia 10 · integración 10; caps duros con procedencia etiquetada (1.17.0); trazabilidad AC-n (1.10.0); advisories stall / stop-signal (1.14.0). Veredicto único (anti-ceremonia, 1.25.0): por default el readiness es UNA pantalla — el veredicto + una línea --- gates: colapsada; --verbose expande las dimensiones y el detalle por repo. Un meta-invariante en la CONSTITUTION gobierna que los gates futuros sigan callados-por-default y colapsen dentro del readiness.

Qué es. Captura la suite golden/approval del comportamiento ACTUAL de un módulo — el único artefacto del loop que el agente no puede authorear, y esa es exactamente su razón de existir. Si el agente escribiera el golden razonando sobre lo que el código "debería" devolver, codificaría la misma lectura parcial que pierde lógica en silencio. Se captura lo que el código HACE, mecánicamente, ejecutándolo.

Cuándo. "characterize", "golden-capture", "capturá el comportamiento viejo" — antes de cualquier migración. uscha-devloop la dispara en Fase 1 (perfil E); uscha-reverse-discovery la orquesta como su Fase 2.

La división de autoría: el agente PUEDE escribir el harness de captura; NO puede crear, renombrar ni editar ningún .approved.

Protocolo

1. Harness de captura (lo escribe el agente): determinístico, corre el módulo ORIGINAL sobre el corpus y serializa TODO output observable. Mismo input → mismo .received, byte a byte.
2. Checklist de no-determinismo (se emite aplicado): timestamps congelados · seeds fijos · orden de maps/sets ordenado · GUIDs/auto-increment normalizados · concurrencia sin filtrar orden · locale objetivo explícito y obligatorio (un golden armado en una máquina con otro locale rompe entero; Windows/SQL Server: riesgo alto) · serialización determinística (claves ordenadas, floats con precisión fija, encoding explícito).
3. Correr la captura → .received. Declarar volátiles ANTES de aprobar (1.15.0): lo que varía entre corridas correctas y no se puede volver determinístico en la fuente se declara en golden.scrub.json; golden-diff enmascara AMBOS lados (solo texto) y reporta cada match vía scrub APARTE — el masking jamás es invisible. gate-check flaggea cualquier edición posterior del archivo.
4. STOP para aprobación humana. El humano revisa y aprueba los .approved — y golden.scrub.json si existe (las reglas de scrub son contrato). La skill termina acá.

Stack de harness: Java → ApprovalTests.Java (JUnit 5, JsonApprovals.verifyAsJson()); C++/otros → dir de fixtures + serializador determinístico + runner custom. Relación: el .approved capturado es el árbitro que golden-diff compara byte a byte durante uscha-devloop.

Qué es. El inverso de discovery: el sistema ya corre y su comportamiento observable ES la verdad. No se inventa nada — se caracteriza lo que ya está, como hechos.

Cuándo. "reverse-discovery", "migrar/modernizar este sistema", "caracterizar el sistema viejo antes de tocarlo".

Protocolo

1. Map (hecho). Solo análisis estático → SYSTEM-MAP.md: cada endpoint/operación/topic público con su contrato · grafo de dependencias (ciclos y hubs flaggeados) · candidatos a módulo (observación del layout ACTUAL, NO propuesta del nuevo). Todo trazable a código: nada de "esto parece que…".
2. Characterize (hecho). El golden en los bordes, delegando en la skill uscha-characterize (o siguiendo su contrato inline si no está instalada). Corpus insuficiente = PARTIAL.
3. Summary (hechos, sin opinión). DISCOVERY-SUMMARY.md: el mapa + el reporte de cobertura del golden (qué bordes están aprobados, cuáles PARTIAL y por qué). La base de hechos que el humano lee para escribir la SPEC de migración. Sin editorializar.

Lo que NO hace (trabajo del humano)

• Escribir la SPEC del comportamiento viejo — el golden ES la spec ejecutable.
• Escribir ADRs de las decisiones implícitas del sistema viejo.
• Decidir la estructura NUEVA (límites de módulos, shared kernel, sync vs eventos) — decisiones forward → adr-refine.

Flow de migración completo: reverse-discovery (hechos) → el humano escribe la SPEC + uscha-adr-refine (decisiones de partición forward) → uscha-devloop (reestructura con golden-diff verde todo el camino) → readiness + gate humano.

Qué es. Genera UN .html autocontenido y navegable (estilo PowerPoint: teclado + click) que documenta un sistema en dos pistas conmutables: comercial/CEO (qué hace, valor, postura de riesgo, estado — sin código, framing plata/tiempo/confiabilidad) y técnica (arquitectura, módulos, contratos, QA, cobertura, deferred).

Cuándo. "document this system", "make the system deck" — a pedido desde uscha-devloop Fase 8 (es reporte, no parte del build verificado).

Estructura (10 slides)

1. Título — sistema, propósito en una línea, fecha, run id.
2. Track switcher — Comercial ⇄ Técnica (default Comercial).
3. [C] Qué hace — lenguaje llano, el trabajo que elimina.
4. [C] Valor y estado — hecho, en vuelo, postura de riesgo.
5. [C] Calidad de un vistazo — cobertura, tests, issues resueltos. Sin jerga.
6. [T] Arquitectura — SVG inline: repos como cajas, flujo como flechas, externos distintos.
7. [T] Contratos / interfaces — las costuras entre repos/módulos.
8. [T] Resultados QA — tabla por tool (reported/fixed/%fixed/deferred/suppressed), cobertura por repo, tests/kLOC, escalaciones.
9. [T] Deferred issues — resumen HONESTO de ISSUES-DEFERRED.md.
10. Smoke checklist — los pasos de verificación manual.

Restricciones de build

• Un solo .html con todo inline — funciona desde disco, deployable tal cual.
• Sin localStorage/sessionStorage (sandboxes) — estado de navegación en variables JS.
• Navegación: flechas, prev/next, índice de dots, Esc = grilla overview, contador visible.
• Diagramas SVG a mano con currentColor/variables CSS — ni raster ni libs externas.
• Dark control-room, pista comercial limpia; accesible (headings semánticos, aria-labels, contraste AA, imprimible).

Output: docs/system-deck.html (o el path que dé el humano); se presenta el path y las 2–3 cosas que mirar primero — el HTML no se pega en el chat.

Qué es. Puntúa el cambio contra RUBRIC.md — criterio cualitativo VERSIONADO (convenciones, ergonomía de API, sanidad del error handling, calidad de docs) con pesos, anchors, criterios negativos y threshold. La skill es un adapter FINO de Claude Code: el núcleo es agnóstico — el prompt neutro (templates/rubric-grader-prompt.md, corre en Codex/Gemini CLI/Cursor/curl/ un humano) + el contrato JSON que rubric-ingest valida (kit 1.23.0).

Cuándo. "grade the rubric", "evaluá la rúbrica" — y uscha-devloop la corre en Fase 3b cuando existe una rúbrica.

Protocolo

1. Validar estructura primero (hechos bloquean): spec-check --rubric RUBRIC.md — cero criterios, IDs duplicados o threshold inválido = exit 1.
2. Grade con contexto AISLADO: leer SOLO diff + rúbrica (jamás el razonamiento del maker); ante la duda, fail — el sesgo optimista es el modo de falla que esta capa combate.
3. Evidence-or-nothing: todo veredicto que afecta el score lleva cita file:line o el engine lo descarta como no sustentado.
4. Ingestar: rubric-ingest --repo X --report reports/rubric-grade.json — score ponderado vs threshold, persiste rubric:grade en el ledger.

Qué es. Una vista de estado autocontenida y de solo lectura: readiness, sub-scores, camino de fases, invariantes, loops de QA y time-lapse. La skill cablea; no calcula. Cada número proviene del ledger.

Cuándo. "mirador", "vista de estado", "bird's-eye", "dashboard del proyecto". Sin QA-LEDGER.json no hay estado que mostrar: se avisa y se frena.

Contrato no negociable

• Truth-pass. qa_ledger.py dashboard --json agrega solo estado existente. Una fuente ausente produce null/[]; el template degrada, jamás inventa.
• Separación de datos. La policy de ejecución es metadata de routing, no score. La telemetría opcional es narrada por el vendor y vive en una franja separada; nunca entra al readiness.
• Solo lectura. No corre gates ni modifica el ledger. readiness --record pertenece al loop, no a esta skill.
• Artefacto generado. Reemplaza solo el bloque entre /*MIRADOR_DATA_START*/ y /*MIRADOR_DATA_END*/ del template y escribe mirador.html.

Flujo

1. Resolver engine y ledger. Usa la primera instalación válida de qa_ledger.py y el QA-LEDGER.json indicado.
2. Renderizar. mirador-render.py ejecuta dashboard --json, mezcla la telemetría sidecar si existe e inyecta const DATA en el template.
3. Abrir best-effort. Intenta abrir mirador.html según la plataforma, nunca falla en headless/CI y siempre imprime el path absoluto.
4. Segundo monitor opcional. mirador-watch.ps1/mirador-watch.sh re-renderiza cada N segundos; la página se refresca sin servidor y cambia solo en checkpoints medidos.

Qué es. Un readout de progreso de una línea, renderizado en el chat, para superficies donde el statusline no se ve (Claude Desktop, Codex, terminales peladas, logs de CI). Lee los mismos hechos MEDIDOS que el statusline — fase derivada, odómetro de loops, barra de acceptance, tests, próximo criterio — y los imprime en un bloque compacto.

Cuándo. "uscha status", "/uscha-status", "cómo vamos", "progreso". Tres niveles de zoom, cada dato una sola vez: el push es la línea de readiness al cierre de cada pasada (ya existe); este es el pull; el mirador es la vista de pájaro.

Contrato no negociable

• Solo lectura. Jamás corre readiness, tests ni gates. Renderiza evidencia ya persistida (ledger["measured"], refrescado por uscha_progress.py) o dice honestamente que no hay ninguna.
• Measured beats narrated. Si no hay medición grabada y solo hay checkboxes de ACCEPTANCE, puede mostrar el conteo pero etiquetado narrado, jamás pasado por medido.
• Truth-pass. Un dato sin fuente encoge el bloque; nunca se vuelve ruido "n/d" ni un número inventado.

Flujo

1. Fuente, en orden. Corre uscha_progress.py si existe (rápido: parsea JSON + un .md, jamás corre tests) y lee .claude/uscha-progress.json; si no, lee QA-LEDGER.json measured directo; sin uscha.config.json no es un proyecto uscha y lo dice.
2. Un bloque compacto. Etiqueta · fase derivada ×loops · barra de acceptance medida · tests · coverage · next → · odómetro por repo (multi-repo, con plateau ⚠) · roadmap · recorded con timestamp y score/band de la última medición.