75e7b9da3d
Dashboard Features: - 8 navigation sections: Overview, Outcomes, Poor CX, FCR, Churn, Agent, Call Explorer, Export - Beyond Brand Identity styling (colors #6D84E3, Outfit font) - RCA Sankey diagram (Driver → Outcome → Churn Risk flow) - Correlation heatmaps (driver co-occurrence, driver-outcome) - Outcome Deep Dive (root causes, correlation, duration analysis) - Export functionality (Excel, HTML, JSON) Blueprint Compliance: - FCR: 4 categories (Primera Llamada/Rellamada × Sin/Con Riesgo de Fuga) - Churn: Binary view (Sin Riesgo de Fuga / En Riesgo de Fuga) - Agent: Talento Para Replicar / Oportunidades de Mejora - Fixed FCR rate calculation (only FIRST_CALL counts as success) Technical: - Streamlit + Plotly for interactive visualizations - Light theme configuration (.streamlit/config.toml) - Fixed Plotly colorbar titlefont deprecation Documentation: - Updated PROJECT_CONTEXT.md, TODO.md, CHANGELOG.md - Added 4 new technical decisions (TD-014 to TD-017) - Created TROUBLESHOOTING.md with 10 common issues Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
9.2 KiB
9.2 KiB
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: base0.4 + freq0.3 + conf0.2 + co-occur0.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)