# TECHNICAL_DECISIONS.md

> Registro de decisiones técnicas con rationale

---

## TD-001: STT Provider

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Necesitamos transcribir 5k-20k llamadas en español con diarización |
| **Opciones evaluadas** | AssemblyAI, Whisper (local), Google Speech-to-Text, AWS Transcribe |
| **Decisión** | AssemblyAI |
| **Rationale** | Mejor diarización español, API simple, coste competitivo (~$0.04/call) |
| **Trade-offs** | Dependencia de servicio externo, costes recurrentes |
| **Reversibilidad** | Alta - interface abstracta permite cambiar provider |

---

## TD-002: LLM for Inference

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Necesitamos extraer RCA labels con evidence de transcripts |
| **Opciones evaluadas** | GPT-4o, GPT-4o-mini, Claude 3.5 Sonnet |
| **Decisión** | GPT-4o-mini (default), configurable |
| **Rationale** | Cost-effective, JSON strict mode, buen español, configurable via CLI |
| **Trade-offs** | Menor capacidad que GPT-4o, posible menor precisión |
| **Reversibilidad** | Alta - `--model` flag permite cambiar |

---

## TD-003: Data Storage

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Almacenar transcripts, analyses, manifests |
| **Opciones evaluadas** | Filesystem JSON, SQLite, DuckDB, PostgreSQL |
| **Decisión** | Filesystem JSON |
| **Rationale** | Simplicidad, debuggability, checkpoint/resume fácil, sin dependencias |
| **Trade-offs** | No óptimo para queries complejos en >50k llamadas |
| **Reversibilidad** | Media - migrar a DB requiere refactor |

---

## TD-004: OBSERVED vs INFERRED Separation

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Outputs deben ser auditables y defendibles |
| **Opciones evaluadas** | Mezclar todo, separar en campos, separar en objetos |
| **Decisión** | Separar en `ObservedFeatures` y campos inferred |
| **Rationale** | Auditoría clara, stakeholders ven qué es hecho vs opinión |
| **Trade-offs** | Estructura más compleja |
| **Reversibilidad** | Baja - cambiar rompe contratos downstream |

---

## TD-005: Evidence Mandatory

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | RCA labels deben ser verificables |
| **Opciones evaluadas** | Evidence opcional, evidence recomendado, evidence obligatorio |
| **Decisión** | Evidence obligatorio (`evidence_spans[]` min 1) |
| **Rationale** | Sin evidence = alucinación, indefendible ante cliente |
| **Trade-offs** | LLM puede fallar si no encuentra evidence |
| **Reversibilidad** | Baja - relajar validation afecta confianza en outputs |

---

## TD-006: Closed Taxonomy + OTHER_EMERGENT

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Balance entre estructura y flexibilidad |
| **Opciones evaluadas** | Taxonomía abierta, taxonomía cerrada, híbrido |
| **Decisión** | Taxonomía cerrada + `OTHER_EMERGENT` para captura |
| **Rationale** | Consistencia en aggregation + captura de nuevos patrones |
| **Trade-offs** | Requiere revisión manual de emergent para promover |
| **Reversibilidad** | Alta - añadir códigos no rompe existentes |

---

## TD-007: Transcript Compression

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Reducir costes de LLM (tokens) |
| **Opciones evaluadas** | No comprimir, extractive summary, rule-based extraction |
| **Decisión** | Rule-based extraction (>60% reducción) |
| **Rationale** | Predecible, sin pérdida de información clave, sin coste adicional |
| **Trade-offs** | Puede perder contexto sutil |
| **Reversibilidad** | Alta - `--no-compression` flag disponible |

---

## TD-008: Severity Scoring Formula

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Priorizar drivers en RCA tree |
| **Opciones evaluadas** | Solo frecuencia, solo confidence, fórmula ponderada |
| **Decisión** | Fórmula ponderada: base*0.4 + freq*0.3 + conf*0.2 + co-occur*0.1 |
| **Rationale** | Balance múltiples factores, configurable |
| **Trade-offs** | Pesos arbitrarios, pueden necesitar ajuste |
| **Reversibilidad** | Alta - pesos en config |

---

## TD-009: Pipeline Checkpointing

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Batches grandes (20k) pueden fallar a mitad |
| **Opciones evaluadas** | Sin checkpoint, checkpoint por archivo, checkpoint por stage |
| **Decisión** | Checkpoint por stage con manifest JSON |
| **Rationale** | Resume granular, debuggable, sin estado complejo |
| **Trade-offs** | Más archivos en filesystem |
| **Reversibilidad** | Alta |

---

## TD-010: Export Formats

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Outputs para diferentes stakeholders |
| **Opciones evaluadas** | Solo JSON, JSON+Excel, JSON+Excel+PDF+Dashboard |
| **Decisión** | JSON + Excel + PDF/HTML |
| **Rationale** | JSON para devs, Excel para analysts, PDF para executives |
| **Trade-offs** | Más código de export, dependencias (openpyxl) |
| **Reversibilidad** | Alta - formats seleccionables |

---

## TD-011: Prompt Versioning Strategy (v2.0)

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Blueprint alignment requires significant prompt changes |
| **Opciones evaluadas** | Modify v1.0 in-place, create v2.0 with deprecation, feature flags |
| **Decisión** | Create v2.0 with v1.0 deprecated but preserved |
| **Rationale** | Backward compatibility, traceability, easy rollback |
| **Trade-offs** | More prompt files to maintain |
| **Reversibilidad** | Alta - `--prompt-version v1.0` flag can be added |

---

## TD-012: Blueprint Alignment Scope

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Gap analysis identified ~20 gaps vs BeyondCX blueprints |
| **Opciones evaluadas** | Implement all, implement high priority only, defer all |
| **Decisión** | Implement HIGH priority gaps (FCR, Churn, Agent, RCALabel) |
| **Rationale** | Core functionality gaps, medium priority can wait for Phase 2 |
| **Trade-offs** | Medium/low priority gaps remain (campaign tracking, customer value) |
| **Reversibilidad** | Media - additional gaps can be added incrementally |

---

## TD-013: DriverOrigin Attribution

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Blueprints require responsibility attribution for each driver |
| **Opciones evaluadas** | 3 origins (agent/customer/company), 4 origins (+process), 5 origins (+unknown) |
| **Decisión** | 5 origins: AGENT, CUSTOMER, COMPANY, PROCESS, UNKNOWN |
| **Rationale** | PROCESS separates systemic issues from company decisions, UNKNOWN for ambiguous cases |
| **Trade-offs** | More categories for LLM to distinguish |
| **Reversibilidad** | Alta - can collapse categories if needed |

---

## TD-014: Dashboard Technology

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Necesitamos visualizar resultados de análisis para clientes |
| **Opciones evaluadas** | Solo exports (Excel/PDF), Streamlit, Dash, React custom |
| **Decisión** | Streamlit + Plotly |
| **Rationale** | Desarrollo rápido, interactividad, Python nativo, fácil de mantener |
| **Trade-offs** | Menos customizable que React, limitado para muy alto tráfico |
| **Reversibilidad** | Media - componentes Plotly reutilizables |

---

## TD-015: Blueprint Terminology Compliance

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Dashboard debe usar terminología exacta de blueprints BeyondCX |
| **Opciones evaluadas** | Usar inglés técnico, usar español parcial, compliance total |
| **Decisión** | Compliance total con terminología de blueprints |
| **Rationale** | Consistencia con documentos cliente, menos confusión |
| **Trade-offs** | Labels más largos en algunos casos |
| **Reversibilidad** | Alta - solo cambios de texto |

---

## TD-016: FCR Rate Calculation

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Blueprint FCR define "Primera Llamada" como éxito |
| **Opciones evaluadas** | FIRST_CALL+RESOLVED, solo FIRST_CALL, custom logic |
| **Decisión** | Solo FIRST_CALL cuenta como FCR success |
| **Rationale** | Blueprint es explícito: "primer contacto por ese motivo" |
| **Trade-offs** | Puede diferir de métricas legacy del cliente |
| **Reversibilidad** | Alta - fórmula configurable |

---

## TD-017: RCA Sankey Visualization

| Campo | Valor |
|-------|-------|
| **Fecha** | 2026-01-19 |
| **Contexto** | Visualizar causalidad Driver → Outcome → Churn |
| **Opciones evaluadas** | Tree diagram, Sunburst, Sankey, Chord |
| **Decisión** | Sankey diagram |
| **Rationale** | Muestra flujo causal, ancho proporcional, muy visual para executives |
| **Trade-offs** | Puede ser confuso con muchos nodos |
| **Reversibilidad** | Alta - componente independiente |

---

## Decisiones Pendientes

| ID | Tema | Status |
|----|------|--------|
| TD-018 | DuckDB para analytics grandes | Pendiente |
| TD-019 | Multi-idioma strategy | Pendiente (Fase 2) |
| TD-020 | Campaign tracking implementation | Pendiente (Fase 2) |
| TD-021 | Customer value analysis | Pendiente (Fase 2) |

---

**Última actualización**: 2026-01-19 (v2.1 Dashboard + Blueprint Compliance)