Case studies¶
Estudios de caso reales de cómo se aplicó el flujo SDD en los changes archivados del roadmap Belico Ecosystem v1. Cada uno sigue la estructura problema → approach SDD → resultado medible. Las métricas son las reales reportadas en los archive_report.md de cada change.
Por qué estos case studies
Demuestran que el flujo SDD (EXPLORE → PROPOSE → SPEC/DESIGN → TASKS → IMPLEMENT → VERIFY → ARCHIVE) no es teoría: produjo software production-grade con métricas auditables y cero regresiones.
Case study 1 — FASE B: Harnesses Tier 2¶
Change: belico-harnesses-tier2-implementation (Change #5).
Problema¶
El stack tenía 5 harnesses Tier 1 operativos, pero faltaban los 10 harnesses Tier 2 del catálogo (anti-AI humanizer, VERITAS citations, stats guardian, Turnitin local, retraction watch, etc.). Sin ellos, la cobertura del catálogo era del 50%.
Approach SDD¶
13 batches de IMPLEMENT con TDD estricto (test primero, código después), reusando el HarnessProtocol validado en Change #2. DI (dependency injection) prioritario sobre mocks. Helpers compartidos para reducir acoplamiento (doi_resolver usado por bibtex + retraction; perplexity_calc por turnitin).
Resultado¶
| Métrica | Valor |
|---|---|
| ACs cumplidos | 50/50 PASS (5 por harness × 10) |
| Tests | 465/465 PASS en 10.51s |
| Regresiones Tier 1 | 0 |
Mutaciones a tools/ heredados |
0 (Strangler Fig 100%) |
| ADs aplicadas | 3 (T2-1 Turnitin local, T2-2 tenant-isolation inactive, T2-3 stats advisory) |
Lección clave: el patrón HarnessProtocol escala — los 10 Tier 2 reusaron el contract sin rediseño. Property-based testing (Hypothesis) fue clave en stats + bibtex + turnitin para edge cases.
Case study 2 — FASE C: Expansión de agentes¶
Change: belico-agents-expansion-fase-c (Change #6).
Problema¶
El pipeline tenía 8 sub-agentes (Change #4), pero faltaban los reviewers (peer, methodology, domain, devils_advocate) y los comerciales (quotation, venue_router, submission_tracker, client_feedback). Sin ellos, la cobertura del catálogo de agentes era del 33%.
Approach SDD¶
13 batches implementando 9 nuevos sub-agentes (5 reviewers + 4 comerciales) reusando el AgentProtocol de Change #4. Optimización de costo: Haiku para revision_coach y venue_router (~39% de ahorro) sin perder calidad. CI workflow auto-review (vs git hooks). Skip de auto-trigger en cambios <50 líneas (anti cost explosion).
Resultado¶
| Métrica | Valor |
|---|---|
| ACs cumplidos | 45/45 PASS (5 por agente × 9) |
| Tests | 290/290 PASS (272 unit + 10 integration + 8 CI) |
| Regresiones | 0 (Tier 1 + Change #4 + Change #5) |
Mutaciones a tools/ |
0 (Strangler Fig 100%) |
| HMAC chain | Verificado real (no mock) en integration tests |
| ADs aplicadas | 4 (FC-1 Engram state, FC-2 GitHub Actions CI, FC-3 skip <50 lines, FC-4 Haiku) |
Lección clave: el AgentProtocol escala perfectamente — los 9 agents reusaron sin rediseñar contract. El CAS lock advisory previene race conditions en la state machine del submission_tracker. La independencia es crítica en devils_advocate.
Case study 3 — FASE D: CLI pública¶
Change: belico-cli-fase-d (Change #7).
Problema¶
El ecosystem no tenía una interfaz pública. Para distribuir el stack vía pip install y para que la documentación (FASE E) tuviera comandos reales que documentar, hacía falta una CLI bilingüe.
Approach SDD¶
9 batches implementando 5 comandos (create-paper, smoke-check, verify, catalog, ecosystem) con Click + Rich (NO Typer, que arrastra Pydantic). Lazy-loading de harnesses/agents por comando para preservar boot rápido. Bilingüismo vía dict centralizado bilingua.py (90 keys, 0 missing). Strangler-fig: la CLI invoca tools/harness vía adapter, nunca muta.
Resultado¶
| Métrica | Valor |
|---|---|
| ACs cumplidos | 30/30 PASS |
| Tests | 178/178 PASS |
Coverage src/belico/ |
89.16% (gate ≥80%) |
| Invariantes preservadas | 7/7 (I1..I7) |
| Boot CLI cold | 278 ms (gate <350ms) |
| Zero-regression suite | 1004 passed (agents + harness + heritage) |
| CI matrix | 9 jobs (Ubuntu/Windows/macOS × Py 3.10/3.11/3.12) |
| ADs aplicadas | 5 (CLI-1 Click+Rich, CLI-2 lazy-loading, CLI-3 bilingua dict, CLI-4 package nuevo, CLI-5 PyPI prep) |
Lección clave: helpers/__init__.py debe quedar VACÍO — los re-exports eager de Rich introducían ~150ms de regresión en boot. tools/init_project.py es TTY-interactivo, así que create-paper emula el scaffold sin ejecutar el script (strangler-fig).
Resumen comparado¶
| Fase | Change | ACs | Tests | Coverage / Nota |
|---|---|---|---|---|
| B | harnesses-tier2 | 50/50 | 465 | ≥90%, 0 regresiones |
| C | agents-fase-c | 45/45 | 290 | 0 regresiones, HMAC real |
| D | cli-fase-d | 30/30 | 178 | 89%, boot 278ms |
Case study 4 — Cliente UC Continental (pendiente)¶
Placeholder — pendiente de producción
El primer paper comercial end-to-end con el cliente UC Continental está en cola (PRD §21.7). Cuando se produzca, este case study documentará el flujo completo: intake → COMPUTE → IMPLEMENT → VERIFY → submission, con las métricas reales de un paper que pasa Turnitin y se vende. Por ahora es un placeholder marcado explícitamente.
Ver también¶
- El ecosistema — el roadmap de 12 semanas.
- El pipeline — el flujo SDD aplicado.
- Arquitectura — los 4 pilares.
Fuente
Métricas extraídas de los archive_report.md de cada change en openspec/changes/.