@trycore/spec-build-harness 0.8.1 → 0.8.2

package/skills/setup-architecture/references/add-method.md

@@ -0,0 +1,53 @@
+# Método ADD — iterar el diseño (Pasos 2–7) — referencia
+
+ADD (Attribute-Driven Design, Len Bass) diseña por **rondas**. Cada ronda ejecuta 7 pasos sobre un
+subconjunto priorizado de drivers del catálogo `0000`. Una ronda produce **un ADR** (a veces refactoriza
+uno previo). Usa la plantilla `assets/adr-add.template.md` de esta skill —instalada junto a estas
+references— (7 secciones = los 7 pasos, con su frontmatter `id/title/date/status/authors/tags/add`).
+
+## Los 7 pasos por iteración
+
+1. **Review inputs** — ya está en `0000-drivers-y-asrs.md`.
+2. **Establecer el objetivo de la iteración** — elige la fase/release y el subconjunto de drivers
+   (empieza por los ASRs críticos, cuadrante (A,A) de la matriz). → §1 del ADR.
+3. **Elegir el elemento a refinar** — sistema completo (primera ronda, top-down) o un módulo/servicio
+   interno (rondas posteriores). → §1 del ADR.
+4. **Elegir conceptos de diseño** — **tácticas** (Bass), **patrones**/estilos, componentes externos o
+   arquitecturas de referencia. Registra las **alternativas descartadas** y por qué. → §2 del ADR.
+5. **Instanciar** — convierte los conceptos en componentes/módulos reales con responsabilidades e
+   **interfaces/contratos**. → §3 del ADR.
+6. **Bocetar vistas y registrar la decisión** — al menos una vista (módulos, C&C o despliegue) en
+   `mermaid`, con la **decisión** y sus **trade-offs**. → §4 del ADR.
+7. **Analizar** (ATAM-lite) — cada driver con veredicto y evidencia; drivers no resueltos vuelven al
+   backlog. → §5 del ADR (delegado a `architecture-evaluator`; ver `atam-lite.md`).
+
+## Tácticas ↔ atributos (guía rápida, no exhaustiva)
+
+| Atributo (QA) | Tácticas típicas (Bass) | Estilos/patrones que las agrupan |
+|---|---|---|
+| Disponibilidad | redundancia, detección (heartbeat/ping), recuperación (rollback, reintento con backoff) | activo-pasivo, health-check, circuit breaker |
+| Rendimiento | gestión de recursos (índices, caché), gestión de demanda (paginación, rate-limit) | CQRS de lectura, caché-aside |
+| Seguridad | resistir (authN/authZ, secretos fuera de código), detectar (auditoría), recuperar | RBAC central, gateway de seguridad, WORM/SIEM |
+| Modificabilidad | encapsular, intermediario, restringir dependencias | capas, hexagonal/puertos-adaptadores, contrato OpenAPI como fuente |
+| Integrabilidad | adaptador, orquestación, límite (bulkhead) | adaptadores por integración, anti-corruption layer |
+| Escalabilidad | replicación, particionamiento, trabajo asíncrono | workers, colas, outbox |
+| Integridad transaccional | transacción, compensación (saga), idempotencia | saga orquestada + outbox |
+
+## Estrategia de iteración
+
+- **Ancho antes que profundo**: primera ronda decide el estilo estructural y el stack del **sistema
+  completo**; rondas posteriores refinan piezas (worker, motor de notificaciones, servicio de RBAC…).
+- **Cimiento primero**: las decisiones fundacionales (identidad/authN, acceso a datos, arquitectura base,
+  design-system) van en las primeras iteraciones — son las que el DoR exigirá antes de abrir épicas de
+  negocio (`layer: foundational`).
+- **Un ADR por decisión coherente**, no por archivo tocado. Si una decisión supersede a otra, marca la
+  vieja `superseded` y enlaza; no borres.
+- **Stack como decisión trazada**: las elecciones de lenguaje/framework/BD/infra son ADRs con su §2
+  (alternativas descartadas). En la fase 5 se consolidan en `stack-allowlist.json`. Si el stack elegido
+  **diverge** del PRD §técnica, regístralo explícitamente como riesgo/restricción (no lo escondas).
+
+## Salida por ronda
+
+1. Escribe `docs/adr/000N-<slug>.md` desde la plantilla, con §1–§4 completas.
+2. Corre `architecture-evaluator` sobre el ADR → completa §5 y §6.
+3. Actualiza `_backlog-arquitectonico.md`: estado de cada driver, riesgos nuevos, fila de bitácora.

package/skills/setup-architecture/references/atam-lite.md

@@ -0,0 +1,44 @@
+# ATAM-lite — evaluación de la arquitectura en papel (ADD Paso 7) — referencia
+
+Análisis de cada ADR **antes de programar**, para descubrir riesgos y trade-offs. Es una versión ligera
+de ATAM (Architecture Tradeoff Analysis Method): no se hace un taller formal con stakeholders, sino un
+barrido adversarial delegado en el agente `architecture-evaluator` (read-only). Alimenta §5/§6 del ADR y
+la sección de riesgos del backlog (estructura completa del backlog — tablero por driver, riesgos
+abiertos, bitácora — en `assets/_backlog-arquitectonico.template.md` de esta skill).
+
+## Qué produce el evaluador, por ADR
+
+- **Veredicto por driver**: para cada driver que el ADR dice satisfacer, ✅/⚠️/❌ con la **evidencia o
+  medida** que lo respalda (o la que falta). Un ⚠️/❌ es un riesgo, no un rechazo.
+- **Puntos de sensibilidad**: propiedades del diseño donde una decisión afecta fuertemente a un atributo
+  (p.ej. "el tamaño del pool de conexiones determina QA-1 rendimiento de lectura").
+- **Trade-offs**: puntos donde una decisión mejora un atributo y empeora otro (p.ej. "el backoff
+  1s/3s/9s da robustez pero puede exceder el P99 ≤ 10 s de la integración externa").
+- **Riesgos**: decisiones sin evidencia, drivers no cubiertos, supuestos sin validar. Cada uno con
+  driver, mitigación planificada e iteración.
+- **Drivers no resueltos**: se devuelven explícitamente al backlog (estado `PENDIENTE`/`EN DISEÑO`).
+
+## Conceptos ATAM que se usan
+
+- **Sensitivity point** — una decisión de la que depende crítica­mente una respuesta de calidad.
+- **Tradeoff point** — un sensitivity point que afecta a más de un atributo en direcciones opuestas.
+- **Risk** — una decisión (o su ausencia) que puede impedir alcanzar la medida de respuesta.
+- **Non-risk** — una decisión que, analizada, se confirma segura para los drivers en juego.
+
+## Reglas del análisis
+
+- **Adversarial y honesto**: el evaluador busca **refutar** que el ADR satisface sus drivers. Ante la
+  duda, marca riesgo, no lo omitas. Es más barato un riesgo en papel que un rediseño en código.
+- **Medida, no opinión**: un driver solo se marca ✅ si hay una medida verificable o un plan de
+  verificación (k6, prueba de carga, matriz de RBAC, etc.). "Parece suficiente" es ⚠️.
+- **No decide negocio**: si el riesgo se resuelve con una decisión de negocio (exponer o no un dato,
+  fijar o aplazar un objetivo de DR), lo marca como **trade-off de negocio** → sube a la revisión única
+  (fase 5), no lo resuelve el modelo.
+- **Cierre trazable**: al mitigar un riesgo en una iteración posterior, se marca ✅ CERRADO en el backlog
+  con el ADR que lo cerró; no se borra la fila.
+
+## Cobertura (invariante del backlog)
+
+Al cerrar la capa, **todo driver del 0000 debe tener estado ≥ ABORDADO** o un riesgo abierto explícito
+que explique por qué no. Un driver crítico (A,A) en `PENDIENTE` sin riesgo declarado es un fallo de la
+capa: no está lista para habilitar el build.

package/skills/setup-architecture/references/drivers-extraction.md

@@ -0,0 +1,39 @@
+# Extracción de drivers / ASRs (ADD Paso 1) — referencia
+
+Objetivo de la fase: producir `docs/adr/0000-drivers-y-asrs.md` **leyendo `docs/`** (solo lectura),
+sobre la plantilla `assets/0000-drivers-y-asrs.template.md` de esta skill (frontmatter + §1–§7). Se
+delega el barrido a `asr-extractor` (fan-out) y la sesión principal consolida. Un **ASR**
+(Architecturally Significant Requirement) es un requisito que, si cambia, cambia la arquitectura.
+
+## De dónde sale cada bloque del 0000
+
+| Bloque del 0000 | Fuente en `docs/` | Cómo derivarlo |
+|---|---|---|
+| **OE** (objetivos de negocio) | `01-prd/` §objetivos, `02-user-story-map/` | Copiar los objetivos específicos + su métrica/meta. Si el PRD no da métrica, proponerla y marcarla como *a validar*. |
+| **UC** (funcionales significativos) | `03-backlog/epicas.md`, `04-historias/HU-*.md` | **Solo** los casos que moldean la arquitectura (integraciones externas, transaccionalidad, RBAC, asincronía, auditoría). No es el backlog completo. |
+| **QA** (escenarios de calidad) | PRD §requisitos no funcionales, AC de las HUs, §técnica | Un escenario de **6 partes** por atributo (rendimiento, disponibilidad, seguridad, integrabilidad, modificabilidad, observabilidad, escalabilidad…). La **medida** debe ser cuantificable. |
+| **CON** (restricciones) | PRD §técnica/§7, política de datos, identidad | Lo que **no** es negociable (stack impuesto, prohibiciones, headers, gates de CI). |
+| **CRN** (concerns) | PRD riesgos, capacidades del equipo, costos | Preocupaciones que condicionan el diseño aunque no sean requisitos formales. |
+| **Prioridad** | juicio + importancia del PRD | Par `(Importancia de negocio, Impacto arquitectónico)` en {A,M,B}. El cuadrante (A,A) son los **ASRs críticos**. |
+| **Plan de iteraciones** | fases del PRD / líneas de release del story map | Una iteración por fase; lista los drivers que ataca cada una. |
+
+## Escenario QA de 6 partes (formato Bass)
+
+Cada QA-N se escribe con exactamente estas seis partes:
+
+- **Fuente** del estímulo (quién/qué lo genera)
+- **Estímulo** (el evento)
+- **Artefacto** (qué parte del sistema recibe el estímulo)
+- **Entorno** (condiciones: normal, pico, degradado)
+- **Respuesta** (qué hace el sistema)
+- **Medida de respuesta** (cuantificable: P95 ≤ X ms, uptime ≥ X%, 0 incidentes…)
+
+Sin medida cuantificable no es un ASR: es un deseo. Si el PRD no la da, **propón** una razonable y déjala
+marcada para validación en la revisión (fase 5), no bloquees.
+
+## Reglas
+
+- **Traza siempre**: cada UC/QA cita las HU/OE/§PRD de las que sale (columna Trazabilidad).
+- **No inventes dominio**: si un atributo no tiene sustento en `docs/`, no lo agregues; si es un hueco
+  real (p.ej. el PRD no fija disponibilidad), decláralo como CRN o riesgo, no como QA fabricado.
+- **Documento vivo**: en re-corridas, añade drivers nuevos de HUs/épicas nuevas; no borres los previos.