Habilidades para pruebas de sistemas distribuidos

Dos habilidades para agentes de codificación de IA que diseñan y ejecutan pruebas impulsadas por afirmaciones para sistemas distribuidos y con estado. Juntas producen un plan de pruebas Markdown estructurado y un informe de hallazgos con veredictos de 10 estados y una clasificación explícita de responsabilidad SUT / harness / checker / entorno. Un revisor lee los dos artefactos y decide si se publica; no es necesario volver a ejecutar nada más.

Funciona con Claude Code, Codex, Copilot CLI, Cursor, Gemini o cualquier agente que lea Markdown y ejecute shell. Las habilidades son simples archivos SKILL.md. El agente las ejecuta; el plan y el informe de hallazgos son el resultado.

Una habilidad diseña el plan. La otra lo ejecuta. Un plan parte de las afirmaciones del producto, genera hipótesis vinculadas a esas afirmaciones y escribe escenarios con el nombre de la afirmación que cada uno intenta refutar. Para escenarios críticos de consistencia, cada escenario también vincula un modelo abstracto (register | queue | log | lock | lease | ledger | …) a un esquema de historial de operaciones, un checker con nombre y un nemesis con evidencia observable de materialización del fallo. El plan termina con un argumento de adecuación de la cobertura y una declaración de confianza conservadora.

Por qué

La práctica habitual para probar sistemas distribuidos y con estado — escribir unas pocas pruebas de integración y darlo por terminado — encuentra una pequeña fracción de los errores que realmente rompen estos sistemas en producción: particiones de red parciales, concurrencia no determinista, recuperación de caídas, actualización/reversión, idempotencia bajo reproducción, ordenación sensible a tiempos.

Estas habilidades imponen un flujo de trabajo con criterio propio que aprovecha el conocimiento ganado con esfuerzo en este campo:

Impulsado por las afirmaciones, no por los tests. Se parte de lo que promete el producto. Cada escenario refuta una afirmación bajo un fallo. Un test nombrado por su afirmación es más difícil de debilitar que uno nombrado por su preparación.
La adecuación de la cobertura es un entregable. El plan termina con un argumento de que los escenarios elegidos son suficientes para publicar, más una lista honesta de lo que permanece sin verificar.
Reutiliza el propio arsenal del SUT. La habilidad de ejecución descubre tests existentes, runbooks y andamiajes de inyección de fallos antes de inventar nada nuevo.
Modelo + historial + checker, no solo caos. Para afirmaciones de seguridad, durabilidad, idempotencia, aislamiento, orden o membresía, cada escenario declara un modelo abstracto, un esquema de historial de operaciones, un checker con nombre (linearizabilidad, serializabilidad, consistencia de sesión, no-lost-ack, exactly-once, …) y cómo trata los resultados ambiguos (timeouts, commits desconocidos, reintentos). Caos más un modelo y un checker, no solo caos.
Sin pases silenciosos. Cada PASS cita evidencia de ejecución del oráculo y la señal que demuestra que el fallo realmente se disparó. Los veredictos provienen de un conjunto de 10 estados, de modo que "el script de caos se ejecutó sin problemas" no puede interpretarse como "la afirmación sobrevivió al fallo". Cada FAIL lleva una etiqueta de responsabilidad SUT / harness / checker / entorno para que quienes reproducen el fallo lleguen a la cola correcta.

Lo que obtienes

De extremo a extremo, las dos habilidades producen:

docs/testing-plans/<slug>.md        ← plan with §0–§9 (see below)
test-sessions/<slug>/<UTC>/
  ├── session-log.md                 ← timeline + toolbox + env probe
  ├── logs/                          ← per-scenario stdout/stderr
  ├── metrics/                       ← metric snapshots
  ├── artifacts/                     ← ephemeral harnesses, dumps
  └── findings/
      ├── <scenario>.md              ← per-scenario verdict (written as run proceeds)
      └── report.md                  ← summary + adequacy + confidence delta

La estructura del plan (un revisor puede leer esto y decidir si publicar sin volver a ejecutar los tests):

0. Architectural summary       — system as it actually exists
1. Scope
1b. Claims under test          — the spine
1c. Missing claims discovered  — docs ↔ code drift
2. SUT model
3. Existing test inventory     — what's already covered
4. Failure-mode hypotheses     — tied to claim IDs
5. Coverage matrix             — claim × hypothesis
6. Technique selection         — from the catalog
6b. Environment requirements
7. Scenarios                   — each named after the claim, with
                                  Target test file + Skeleton
   7.M Model / history /       — mandatory when the scenario falsifies
       checker discipline        a claim in {safety, durability,
                                  idempotency, isolation, ordering,
                                  membership}: model under test,
                                  operation-history schema, named
                                  checker, nemesis + landing evidence,
                                  ambiguous-outcome handling, reduction
                                  plan (SUT/harness/checker/env blame)
7b. Coverage adequacy argument — why these tests are enough
7c. Residual uncertainty       — what stays unverified, and why ok
7d. Confidence statement       — the reviewer's verdict
8. What this plan does NOT cover
9. Open questions / followups

Ejemplo de bloque §7.M (extracto de un plan)

### Scenario S3: linearizable_append_under_partition
- Falsifies if it FAILs: C1 (every acknowledged append is durable
  and linearisable), C5 (leader election completes within 5s)
- Workload: 8 clients, 70% append / 30% read, 5min, key-skew zipf
- Faults: asymmetric partition isolating current leader at T+60s
  for 30s
- Oracle: linearizability via Porcupine over per-key histories

§7.M (model / history / checker discipline)
- Model under test:    log
- Operation history:   default 11-field schema (op id, process id,
                       invoke/complete ts, op type, key, input,
                       output, error, timeout marker, node seen,
                       fault epoch). Recorded in-process + server-
                       side audit.
- Checker:             linearizability (Porcupine) per-key, then
                       no-lost-ack against final state
- Nemesis + landing:   asymmetric-partition (iptables drop one
                       direction). Landing evidence = iptables drop
                       counter goes 0 → 14,712 over the 30s window
                       AND raft log emits "leader-lost; starting
                       election" within 2s of injection.
- Ambiguous outcomes:  timeouts → timeout_marker=true, complete_ts
                       =null, treated as could-have-succeeded;
                       retries are separate ops sharing input
- Reduction plan:      if FAIL, bisect fault window + fix seed, then
                       classify SUT / harness / checker / environment
                       per references/test-case-reduction.md

Ejemplo de fila de informe de hallazgos

ID	Veredicto	Evidencia de materialización del nemesis	Clase de reducción
S3	`PASS-hardening`	contador iptables 0→14,712; reelección de raft en T+1.8s	n/a
S4	`FAIL-reproducible`	partición materializada; Elle: anomalía G2-item en la clave K17	SUT
S7	`INCONCLUSIVE-fault-not-proven`	regla iptables instalada pero el contador se quedó en 0 — cadena incorrecta	harness
S9	`PARTIAL-model`	materialización correcta; el checker cubrió por clave, no entre claves	n/a

distributed-system-testing — Actualizado!