@saulwade/swl-ses 2.3.0 → 2.3.1

package/habilidades/proceso-ddia-fundamentos/SKILL.md

@@ -1,255 +1,255 @@
----
-name: proceso-ddia-fundamentos
-description: >
-  Conceptos fundamentales del libro "Designing Data-Intensive Applications" de
-  Martin Kleppmann aplicables a sistemas no-distribuidos (como SWL): Cap 1
-  Reliability/Scalability/Maintainability como framework de evaluación, Cap 4
-  Schema Evolution con backward/forward compatibility, Cap 12 End-to-End
-  Argument y Trust-but-Verify. Cargar al diseñar manifiestos versionados,
-  evaluar arquitectura de un módulo, decidir dónde validar correctitud.
-when_to_use: >
-  Usar cuando el usuario menciona schema versioning, backward/forward compat,
-  end-to-end verification, trust but verify, reliability scalability
-  maintainability, RSM framework, Operability Simplicity Evolvability,
-  schema-evolution, evaluar arquitectura, decidir dónde validar.
----
-
-# DDIA Fundamentos — RSM, Schema Evolution, End-to-End
-
-Adaptado de Martin Kleppmann, *"Designing Data-Intensive Applications"*
-(O'Reilly, 2017). Skill cubre los tres ejes del libro que aplican a SWL:
-
-- **Capítulo 1** — Reliability, Scalability, Maintainability como framework.
-- **Capítulo 4** — Schema Evolution (back/forward compatibility).
-- **Capítulo 12** — End-to-End Argument + Trust-but-Verify.
-
-Los demás capítulos del libro (2-3 data models / storage, 5-10 distributed
-systems) tratan dominios que SWL no es (no es BD, no es sistema distribuido).
-Se descartan por filtro de dominio (regla `arquitectura.md`).
-
-## Cuándo cargar
-
-- Diseñar un schema nuevo (manifest, frontmatter, JSON Schema) que
-  evolucionará en el tiempo.
-- Auditar un módulo SWL para evaluar Reliability/Scalability/Maintainability.
-- Decidir dónde poner una validación: en cada capa o solo end-to-end.
-- Resolver una duda sobre "¿esto se rompe si actualizo el sistema?" — es
-  pregunta de schema compatibility.
-
-## Cuándo NO cargar
-
-- Discusiones sobre replication, partitioning, consenso (Paxos/Raft) — esos
-  capítulos DDIA no aplican a SWL.
-- Streaming/event sourcing avanzado — cargar `Skill("proceso-ddia-streaming")`.
-- Optimización puntual de query SQL — cargar `Skill("performance-baseline")`.
-
----
-
-## Parte 1 — Reliability, Scalability, Maintainability (RSM)
-
-Cita textual del libro (DDIA p.18, línea 1411-1453):
-
-> "It is well known that the majority of the cost of software is not in its
-> initial development, but in its ongoing maintenance — fixing bugs, keeping
-> its systems operational, investigating failures, adapting it to new
-> platforms, modifying it for new use cases, repaying technical debt, and
-> adding new features."
-
-### Las 3 dimensiones del RSM
-
-**Reliability** — el sistema sigue funcionando correctamente bajo:
-- Hardware faults
-- Software errors
-- Human errors
-
-Tipos de respuesta:
-- **Fault-tolerant**: el sistema absorbe la falla sin propagarla.
-- **Resilient**: degrada con gracia, no en cascada.
-
-**Aplicación a SWL**: hooks bloqueantes (`calidad-pre-commit`,
-`escaneo-secretos`) son fault-tolerance. Las escrituras atómicas
-(`hooks/lib/atomic-write.js`) son resilience contra crashes durante write.
-
-**Scalability** — cómo cambia el rendimiento cuando crece la carga:
-- Describir **carga** (parámetros: throughput, concurrent users, etc.)
-- Describir **rendimiento** (latencia: p50, p95, p99)
-
-**Aplicación a SWL**: las métricas `Skill("performance-baseline")` siguen
-este modelo. Carga = sesiones concurrentes, archivos por proyecto, agentes
-en cadena. Rendimiento = latencia de hooks, tiempo de respuesta de
-validadores.
-
-**Maintainability** — tres principios de diseño del libro:
-
-> "Operability: Make it easy for operations teams to keep the system running
-> smoothly.
-> Simplicity: Make it easy for new engineers to understand the system, by
-> removing as much complexity as possible from the system. (Note this is
-> not the same as simplicity of the user interface.)
-> Evolvability: Make it easy for engineers to make changes to the system in
-> the future, adapting it for unanticipated use cases as requirements
-> change. Also known as extensibility, modifiability, or plasticity."
-> (DDIA p.18-19, líneas 1435-1449)
-
-**Aplicación a SWL**:
-
-| Principio DDIA | Implementación SWL |
-|---|---|
-| Operability | `/swl:status salud`, `/swl:status dashboard`, `/swl:doctor`, runbooks |
-| Simplicity | Skills ≤300 líneas, módulos profundos (Ousterhout), zero-deps en `hooks/lib/` |
-| Evolvability | ADRs versionados, schemas opcionales aditivos, fragments compartidos |
-
-### Cómo usar RSM como rúbrica de evaluación
-
-Antes de declarar un módulo "listo", pregúntate:
-
-1. **Reliability**: ¿qué pasa si una entrada inesperada llega? ¿Si un hook
-   externo falla? ¿Si el filesystem se llena?
-2. **Scalability**: ¿el módulo escala con el tamaño del proyecto del
-   usuario? Si tiene 1000 archivos vs 10, ¿degrada linealmente o se
-   cuadratiza?
-3. **Maintainability** (los 3 sub-principios):
-   - ¿Un operario nuevo puede operarlo sin leer todo el código?
-   - ¿Un ingeniero nuevo puede entenderlo sin un curso?
-   - ¿Un cambio de requisito se acomoda sin reescribir?
-
-Si la respuesta es "no" a más de uno, el módulo necesita refactor antes de
-release.
-
----
-
-## Parte 2 — Schema Evolution (Cap 4)
-
-Cita textual del libro (DDIA p.112, línea 5706-5719):
-
-> "Backward compatibility — Newer code can read data that was written by
-> older code.
->
-> Forward compatibility — Older code can read data that was written by
-> newer code.
->
-> Backward compatibility is normally not hard to achieve: as author of the
-> newer code, you know the format of data written by older code, and so
-> you can explicitly handle it (if necessary by simply keeping the old code
-> to read the old data). Forward compatibility can be trickier, because it
-> requires older code to ignore additions made by a newer version of the
-> code."
-
-### Las 2 direcciones de compatibilidad
-
-Cuando un schema evoluciona, hay dos preguntas distintas:
-
-| Pregunta | Tipo | Difficulty |
-|---|---|---|
-| ¿Código nuevo lee datos viejos? | Backward | Fácil |
-| ¿Código viejo lee datos nuevos? | Forward | Más difícil |
-
-**Backward compat es fácil**: el código nuevo conoce ambas versiones del
-schema, puede manejar los dos formatos.
-
-**Forward compat es difícil**: el código viejo NO sabe que existe el campo
-nuevo. Para que funcione, el código viejo debe **ignorar campos
-desconocidos** sin romperse.
-
-### Aplicación a schemas SWL
-
-SWL tiene 14 archivos `schemas/*.schema.json`. Reglas operativas:
-
-1. **Campos nuevos siempre opcionales**: agregar `myField: { type: "..." }`
-   sin marcarlo `required`. Código viejo lo ignora (forward-compat OK).
-   Código nuevo lo usa si está presente (backward-compat OK).
-
-2. **NUNCA renombrar campos en MINOR/PATCH**: rename = breaking. Si hay
-   que renombrar, mantener ambos durante 1 release (deprecación) y
-   eliminar en el MAJOR siguiente.
-
-3. **NUNCA cambiar tipo de un campo en MINOR/PATCH**: cambiar `string` →
-   `array` rompe ambas direcciones. Es MAJOR.
-
-4. **Agregar enum value es compatible**: si `nivelRiesgo` acepta
-   `[BAJO, MEDIO, ALTO]`, agregar `CRÍTICO` es backward-compat (código
-   nuevo lo entiende, código viejo lo rechaza pero no se rompe).
-
-5. **Eliminar enum value es breaking**: código nuevo rechaza algo que
-   código viejo escribía.
-
-### Detección de breaking changes
-
-Helper `scripts/lib/schema-version.js` (creado en F4) implementa estas
-reglas. Uso esperado:
-
-```js
-const { verificarCompatibilidad } = require('./scripts/lib/schema-version');
-const r = verificarCompatibilidad(documento, schema);
-// r = { compatible: bool, modo: "backward"|"forward"|"none", advertencias }
-```
-
-Tres modos según versiones:
-- Doc 1.0.0 + Schema 1.0.0 → `modo: "none"` (idénticas).
-- Doc 1.0.0 + Schema 1.1.0 → `modo: "forward"` (dato viejo, código nuevo).
-- Doc 1.1.0 + Schema 1.0.0 → `modo: "backward"` (dato nuevo, código viejo).
-- Doc 2.0.0 + Schema 1.0.0 → `compatible: false` (MAJOR rompe).
-
----
-
-## Parte 3 — End-to-End Argument (Cap 12)
-
-Concepto del libro: la verificación de correctitud debe vivir en la
-frontera del sistema (end-to-end), no en cada capa intermedia.
-
-> "The End-to-End Argument for Databases" (DDIA p.516, sección referenciada)
-
-### El principio aplicado
-
-Si validas en cada capa intermedia:
-- Capa 1: valida → pasa
-- Capa 2: valida → pasa
-- Capa 3: valida → pasa
-- Resultado: dato corrupto entregado al usuario porque ninguna capa
-  verificó la **invariante de negocio** completa.
-
-Si validas end-to-end:
-- Capa 1, 2, 3: hacen su trabajo sin validar
-- Frontera del sistema: verifica la invariante completa
-- Resultado: si falla, se detecta antes de entregar al usuario.
-
-### Aplicación a SWL
-
-- `/swl:verificar` con goal-backward 4 niveles es end-to-end.
-- Hooks de validación intermedios (`calidad-pre-commit`,
-  `escaneo-secretos`) son fault-tolerance, no end-to-end. Detectan
-  problemas obvios temprano para reducir blast radius — no reemplazan la
-  verificación end-to-end.
-- Las dos capas son complementarias: hooks rápidos en cada step, verifier
-  end-to-end al cierre de fase.
-
-### Trust-but-Verify (Cap 12, p.528)
-
-El sistema debe **confiar provisionalmente** en sus componentes
-(hooks pasan → asumimos correcto) pero **verificar** la invariante final
-con evidencia, no con auto-reporte de los componentes.
-
-Aplicación SWL: regla `verificar-citas-normativas.md` aplica este
-principio a citas archivo:línea — un sub-agente reportó "está
-implementado en X:42"; el padre verifica con `Read`+`grep` antes de
-aceptar.
-
----
-
-## Resumen — qué se llevó SWL del libro
-
-| Concepto DDIA | Dónde vive en SWL |
-|---|---|
-| Reliability/Scalability/Maintainability como framework | Este skill como rúbrica de evaluación |
-| Operability / Simplicity / Evolvability | Skills ≤300 líneas + observabilidad-swl + ADRs |
-| Backward / Forward compat | `$schemaVersion` + `scripts/lib/schema-version.js` (F4) |
-| End-to-End Argument | `/swl:verificar` goal-backward |
-| Trust-but-Verify | regla `verificar-citas-normativas.md` |
-
-## Origen
-
-Skill creado el 2026-05-18 como parte de Opción B de integración
-`temp/Designing Data Intensive Applications by Martin Kleppmann.md`. Ver
-ADR-0025 para la decisión de scope. Skill hermano:
-`proceso-ddia-streaming` (Cap 11 event sourcing aplicado a
-`evolucion/*.jsonl`).
+---
+name: proceso-ddia-fundamentos
+description: >
+  Conceptos fundamentales del libro "Designing Data-Intensive Applications" de
+  Martin Kleppmann aplicables a sistemas no-distribuidos (como SWL): Cap 1
+  Reliability/Scalability/Maintainability como framework de evaluación, Cap 4
+  Schema Evolution con backward/forward compatibility, Cap 12 End-to-End
+  Argument y Trust-but-Verify. Cargar al diseñar manifiestos versionados,
+  evaluar arquitectura de un módulo, decidir dónde validar correctitud.
+when_to_use: >
+  Usar cuando el usuario menciona schema versioning, backward/forward compat,
+  end-to-end verification, trust but verify, reliability scalability
+  maintainability, RSM framework, Operability Simplicity Evolvability,
+  schema-evolution, evaluar arquitectura, decidir dónde validar.
+---
+
+# DDIA Fundamentos — RSM, Schema Evolution, End-to-End
+
+Adaptado de Martin Kleppmann, *"Designing Data-Intensive Applications"*
+(O'Reilly, 2017). Skill cubre los tres ejes del libro que aplican a SWL:
+
+- **Capítulo 1** — Reliability, Scalability, Maintainability como framework.
+- **Capítulo 4** — Schema Evolution (back/forward compatibility).
+- **Capítulo 12** — End-to-End Argument + Trust-but-Verify.
+
+Los demás capítulos del libro (2-3 data models / storage, 5-10 distributed
+systems) tratan dominios que SWL no es (no es BD, no es sistema distribuido).
+Se descartan por filtro de dominio (regla `arquitectura.md`).
+
+## Cuándo cargar
+
+- Diseñar un schema nuevo (manifest, frontmatter, JSON Schema) que
+  evolucionará en el tiempo.
+- Auditar un módulo SWL para evaluar Reliability/Scalability/Maintainability.
+- Decidir dónde poner una validación: en cada capa o solo end-to-end.
+- Resolver una duda sobre "¿esto se rompe si actualizo el sistema?" — es
+  pregunta de schema compatibility.
+
+## Cuándo NO cargar
+
+- Discusiones sobre replication, partitioning, consenso (Paxos/Raft) — esos
+  capítulos DDIA no aplican a SWL.
+- Streaming/event sourcing avanzado — cargar `Skill("proceso-ddia-streaming")`.
+- Optimización puntual de query SQL — cargar `Skill("performance-baseline")`.
+
+---
+
+## Parte 1 — Reliability, Scalability, Maintainability (RSM)
+
+Cita textual del libro (DDIA p.18, línea 1411-1453):
+
+> "It is well known that the majority of the cost of software is not in its
+> initial development, but in its ongoing maintenance — fixing bugs, keeping
+> its systems operational, investigating failures, adapting it to new
+> platforms, modifying it for new use cases, repaying technical debt, and
+> adding new features."
+
+### Las 3 dimensiones del RSM
+
+**Reliability** — el sistema sigue funcionando correctamente bajo:
+- Hardware faults
+- Software errors
+- Human errors
+
+Tipos de respuesta:
+- **Fault-tolerant**: el sistema absorbe la falla sin propagarla.
+- **Resilient**: degrada con gracia, no en cascada.
+
+**Aplicación a SWL**: hooks bloqueantes (`calidad-pre-commit`,
+`escaneo-secretos`) son fault-tolerance. Las escrituras atómicas
+(`hooks/lib/atomic-write.js`) son resilience contra crashes durante write.
+
+**Scalability** — cómo cambia el rendimiento cuando crece la carga:
+- Describir **carga** (parámetros: throughput, concurrent users, etc.)
+- Describir **rendimiento** (latencia: p50, p95, p99)
+
+**Aplicación a SWL**: las métricas `Skill("performance-baseline")` siguen
+este modelo. Carga = sesiones concurrentes, archivos por proyecto, agentes
+en cadena. Rendimiento = latencia de hooks, tiempo de respuesta de
+validadores.
+
+**Maintainability** — tres principios de diseño del libro:
+
+> "Operability: Make it easy for operations teams to keep the system running
+> smoothly.
+> Simplicity: Make it easy for new engineers to understand the system, by
+> removing as much complexity as possible from the system. (Note this is
+> not the same as simplicity of the user interface.)
+> Evolvability: Make it easy for engineers to make changes to the system in
+> the future, adapting it for unanticipated use cases as requirements
+> change. Also known as extensibility, modifiability, or plasticity."
+> (DDIA p.18-19, líneas 1435-1449)
+
+**Aplicación a SWL**:
+
+| Principio DDIA | Implementación SWL |
+|---|---|
+| Operability | `/swl:status salud`, `/swl:status dashboard`, `/swl:doctor`, runbooks |
+| Simplicity | Skills ≤300 líneas, módulos profundos (Ousterhout), zero-deps en `hooks/lib/` |
+| Evolvability | ADRs versionados, schemas opcionales aditivos, fragments compartidos |
+
+### Cómo usar RSM como rúbrica de evaluación
+
+Antes de declarar un módulo "listo", pregúntate:
+
+1. **Reliability**: ¿qué pasa si una entrada inesperada llega? ¿Si un hook
+   externo falla? ¿Si el filesystem se llena?
+2. **Scalability**: ¿el módulo escala con el tamaño del proyecto del
+   usuario? Si tiene 1000 archivos vs 10, ¿degrada linealmente o se
+   cuadratiza?
+3. **Maintainability** (los 3 sub-principios):
+   - ¿Un operario nuevo puede operarlo sin leer todo el código?
+   - ¿Un ingeniero nuevo puede entenderlo sin un curso?
+   - ¿Un cambio de requisito se acomoda sin reescribir?
+
+Si la respuesta es "no" a más de uno, el módulo necesita refactor antes de
+release.
+
+---
+
+## Parte 2 — Schema Evolution (Cap 4)
+
+Cita textual del libro (DDIA p.112, línea 5706-5719):
+
+> "Backward compatibility — Newer code can read data that was written by
+> older code.
+>
+> Forward compatibility — Older code can read data that was written by
+> newer code.
+>
+> Backward compatibility is normally not hard to achieve: as author of the
+> newer code, you know the format of data written by older code, and so
+> you can explicitly handle it (if necessary by simply keeping the old code
+> to read the old data). Forward compatibility can be trickier, because it
+> requires older code to ignore additions made by a newer version of the
+> code."
+
+### Las 2 direcciones de compatibilidad
+
+Cuando un schema evoluciona, hay dos preguntas distintas:
+
+| Pregunta | Tipo | Difficulty |
+|---|---|---|
+| ¿Código nuevo lee datos viejos? | Backward | Fácil |
+| ¿Código viejo lee datos nuevos? | Forward | Más difícil |
+
+**Backward compat es fácil**: el código nuevo conoce ambas versiones del
+schema, puede manejar los dos formatos.
+
+**Forward compat es difícil**: el código viejo NO sabe que existe el campo
+nuevo. Para que funcione, el código viejo debe **ignorar campos
+desconocidos** sin romperse.
+
+### Aplicación a schemas SWL
+
+SWL tiene 14 archivos `schemas/*.schema.json`. Reglas operativas:
+
+1. **Campos nuevos siempre opcionales**: agregar `myField: { type: "..." }`
+   sin marcarlo `required`. Código viejo lo ignora (forward-compat OK).
+   Código nuevo lo usa si está presente (backward-compat OK).
+
+2. **NUNCA renombrar campos en MINOR/PATCH**: rename = breaking. Si hay
+   que renombrar, mantener ambos durante 1 release (deprecación) y
+   eliminar en el MAJOR siguiente.
+
+3. **NUNCA cambiar tipo de un campo en MINOR/PATCH**: cambiar `string` →
+   `array` rompe ambas direcciones. Es MAJOR.
+
+4. **Agregar enum value es compatible**: si `nivelRiesgo` acepta
+   `[BAJO, MEDIO, ALTO]`, agregar `CRÍTICO` es backward-compat (código
+   nuevo lo entiende, código viejo lo rechaza pero no se rompe).
+
+5. **Eliminar enum value es breaking**: código nuevo rechaza algo que
+   código viejo escribía.
+
+### Detección de breaking changes
+
+Helper `scripts/lib/schema-version.js` (creado en F4) implementa estas
+reglas. Uso esperado:
+
+```js
+const { verificarCompatibilidad } = require('./scripts/lib/schema-version');
+const r = verificarCompatibilidad(documento, schema);
+// r = { compatible: bool, modo: "backward"|"forward"|"none", advertencias }
+```
+
+Tres modos según versiones:
+- Doc 1.0.0 + Schema 1.0.0 → `modo: "none"` (idénticas).
+- Doc 1.0.0 + Schema 1.1.0 → `modo: "forward"` (dato viejo, código nuevo).
+- Doc 1.1.0 + Schema 1.0.0 → `modo: "backward"` (dato nuevo, código viejo).
+- Doc 2.0.0 + Schema 1.0.0 → `compatible: false` (MAJOR rompe).
+
+---
+
+## Parte 3 — End-to-End Argument (Cap 12)
+
+Concepto del libro: la verificación de correctitud debe vivir en la
+frontera del sistema (end-to-end), no en cada capa intermedia.
+
+> "The End-to-End Argument for Databases" (DDIA p.516, sección referenciada)
+
+### El principio aplicado
+
+Si validas en cada capa intermedia:
+- Capa 1: valida → pasa
+- Capa 2: valida → pasa
+- Capa 3: valida → pasa
+- Resultado: dato corrupto entregado al usuario porque ninguna capa
+  verificó la **invariante de negocio** completa.
+
+Si validas end-to-end:
+- Capa 1, 2, 3: hacen su trabajo sin validar
+- Frontera del sistema: verifica la invariante completa
+- Resultado: si falla, se detecta antes de entregar al usuario.
+
+### Aplicación a SWL
+
+- `/swl:verificar` con goal-backward 4 niveles es end-to-end.
+- Hooks de validación intermedios (`calidad-pre-commit`,
+  `escaneo-secretos`) son fault-tolerance, no end-to-end. Detectan
+  problemas obvios temprano para reducir blast radius — no reemplazan la
+  verificación end-to-end.
+- Las dos capas son complementarias: hooks rápidos en cada step, verifier
+  end-to-end al cierre de fase.
+
+### Trust-but-Verify (Cap 12, p.528)
+
+El sistema debe **confiar provisionalmente** en sus componentes
+(hooks pasan → asumimos correcto) pero **verificar** la invariante final
+con evidencia, no con auto-reporte de los componentes.
+
+Aplicación SWL: regla `verificar-citas-normativas.md` aplica este
+principio a citas archivo:línea — un sub-agente reportó "está
+implementado en X:42"; el padre verifica con `Read`+`grep` antes de
+aceptar.
+
+---
+
+## Resumen — qué se llevó SWL del libro
+
+| Concepto DDIA | Dónde vive en SWL |
+|---|---|
+| Reliability/Scalability/Maintainability como framework | Este skill como rúbrica de evaluación |
+| Operability / Simplicity / Evolvability | Skills ≤300 líneas + observabilidad-swl + ADRs |
+| Backward / Forward compat | `$schemaVersion` + `scripts/lib/schema-version.js` (F4) |
+| End-to-End Argument | `/swl:verificar` goal-backward |
+| Trust-but-Verify | regla `verificar-citas-normativas.md` |
+
+## Origen
+
+Skill creado el 2026-05-18 como parte de Opción B de integración
+`temp/Designing Data Intensive Applications by Martin Kleppmann.md`. Ver
+ADR-0025 para la decisión de scope. Skill hermano:
+`proceso-ddia-streaming` (Cap 11 event sourcing aplicado a
+`evolucion/*.jsonl`).