susana/BeyondCX_Insights
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
BeyondCX_Insights/config/rca_taxonomy.yaml
sujucu70 75e7b9da3d feat: Add Streamlit dashboard with Blueprint compliance (v2.1.0) 
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>
2026-01-19 16:27:30 +01:00

691 lines
20 KiB
YAML
Raw Permalink Blame History

# ============================================
# CXInsights - RCA Taxonomy (Utilities/Energy)
# ============================================
# Version: 2.0.0
# Domain: Utilities / Energy
# Last Updated: 2026-01-19
# ============================================
version: "2.0.0"
domain: "utilities_energy"
status: "active"
# ============================================
# LOST SALES / LOST OPPORTUNITIES DRIVERS
# ============================================
# Oportunidades perdidas en utilities/energía
# ============================================
lost_sales:
# --- Objeciones del Cliente ---
PRICE_TOO_HIGH:
category: "objection"
description: "Cliente considera la tarifa demasiado alta"
description_en: "Customer considers rate/tariff too high"
severity_weight: 0.8
requires_evidence: true
NO_INTEREST_IN_UPGRADE:
category: "objection"
description: "Cliente no interesado en cambio de tarifa o servicios adicionales"
description_en: "Customer not interested in rate change or additional services"
severity_weight: 0.6
requires_evidence: true
COMPETITOR_PREFERENCE:
category: "objection"
description: "Cliente prefiere oferta de otra comercializadora"
description_en: "Customer prefers another energy provider offer"
severity_weight: 0.9
requires_evidence: true
TIMING_NOT_RIGHT:
category: "objection"
description: "No es buen momento (mudanza, cambios en consumo)"
description_en: "Not the right time (moving, consumption changes)"
severity_weight: 0.5
requires_evidence: true
CONTRACT_PERMANENCE:
category: "objection"
description: "Cliente rechaza por permanencia o penalizaciones"
description_en: "Customer rejects due to permanence or penalties"
severity_weight: 0.7
requires_evidence: true
DISTRUST_OF_OFFERS:
category: "objection"
description: "Cliente desconfía de las ofertas telefónicas"
description_en: "Customer distrusts phone offers"
severity_weight: 0.6
requires_evidence: true
# --- Fallos del Agente ---
BENEFITS_NOT_EXPLAINED:
category: "agent_failure"
description: "Beneficios de la oferta no explicados claramente"
description_en: "Offer benefits not clearly explained"
severity_weight: 0.8
requires_evidence: true
NO_RETENTION_ATTEMPT:
category: "agent_failure"
description: "No se intentó retener al cliente"
description_en: "No retention attempt made"
severity_weight: 0.9
requires_evidence: true
POOR_RATE_RECOMMENDATION:
category: "agent_failure"
description: "Recomendación de tarifa inadecuada al consumo"
description_en: "Rate recommendation not suited to consumption"
severity_weight: 0.7
requires_evidence: true
NO_SAVINGS_CALCULATION:
category: "agent_failure"
description: "No se calculó el ahorro potencial"
description_en: "No potential savings calculation provided"
severity_weight: 0.6
requires_evidence: true
WRONG_SERVICE_OFFERED:
category: "agent_failure"
description: "Servicio ofrecido no aplica al cliente"
description_en: "Service offered not applicable to customer"
severity_weight: 0.7
requires_evidence: true
# --- Problemas de Proceso ---
SYSTEM_UNAVAILABLE:
category: "process"
description: "Sistema no disponible para procesar cambio"
description_en: "System unavailable to process change"
severity_weight: 0.7
requires_evidence: true
SERVICE_NOT_AVAILABLE_AREA:
category: "process"
description: "Servicio no disponible en la zona del cliente"
description_en: "Service not available in customer area"
severity_weight: 0.6
requires_evidence: true
DOCUMENTATION_REQUIRED:
category: "process"
description: "Requiere documentación que cliente no tiene"
description_en: "Requires documentation customer doesn't have"
severity_weight: 0.5
requires_evidence: true
# --- Emergente ---
OTHER_EMERGENT:
category: "emergent"
description: "Causa emergente (requiere revisión manual)"
description_en: "Emergent cause (requires manual review)"
severity_weight: 0.5
requires_evidence: true
requires_proposed_label: true
# ============================================
# POOR CUSTOMER EXPERIENCE DRIVERS
# ============================================
# Causas de mala experiencia - Utilities/Energía
# ============================================
poor_cx:
# --- Tiempo de Espera ---
LONG_HOLD:
category: "wait_time"
description: "Tiempo de espera prolongado"
description_en: "Long hold time"
severity_weight: 0.7
requires_evidence: true
observable: true
LONG_SILENCE:
category: "wait_time"
description: "Silencios prolongados durante la llamada"
description_en: "Long silences during call"
severity_weight: 0.5
requires_evidence: true
observable: true
# --- Transferencias ---
MULTI_TRANSFER:
category: "transfer"
description: "Múltiples transferencias entre departamentos"
description_en: "Multiple transfers between departments"
severity_weight: 0.8
requires_evidence: true
observable: true
WRONG_DEPARTMENT:
category: "transfer"
description: "Derivado a departamento incorrecto"
description_en: "Transferred to wrong department"
severity_weight: 0.7
requires_evidence: true
COLD_TRANSFER:
category: "transfer"
description: "Transferencia sin contexto al nuevo agente"
description_en: "Transfer without context to new agent"
severity_weight: 0.7
requires_evidence: true
# --- Comportamiento del Agente ---
LOW_EMPATHY:
category: "agent_behavior"
description: "Falta de empatía ante problema del cliente"
description_en: "Lack of empathy for customer problem"
severity_weight: 0.8
requires_evidence: true
RUDE_BEHAVIOR:
category: "agent_behavior"
description: "Comportamiento descortés o impaciente"
description_en: "Rude or impatient behavior"
severity_weight: 0.9
requires_evidence: true
NOT_LISTENING:
category: "agent_behavior"
description: "Agente no escucha la situación del cliente"
description_en: "Agent not listening to customer situation"
severity_weight: 0.7
requires_evidence: true
INTERRUPTIONS:
category: "agent_behavior"
description: "Agente interrumpe al cliente"
description_en: "Agent interrupts customer"
severity_weight: 0.6
requires_evidence: true
observable: true
# --- Resolución - Utilities Specific ---
OUTAGE_NOT_EXPLAINED:
category: "resolution"
description: "No se explicó causa o duración de la avería"
description_en: "Outage cause or duration not explained"
severity_weight: 0.8
requires_evidence: true
BILLING_NOT_CLARIFIED:
category: "resolution"
description: "Factura no explicada claramente"
description_en: "Bill not clearly explained"
severity_weight: 0.7
requires_evidence: true
ISSUE_NOT_RESOLVED:
category: "resolution"
description: "Problema no resuelto en la llamada"
description_en: "Issue not resolved during call"
severity_weight: 0.9
requires_evidence: true
PARTIAL_RESOLUTION:
category: "resolution"
description: "Resolución parcial del problema"
description_en: "Partial issue resolution"
severity_weight: 0.6
requires_evidence: true
INCORRECT_INFO:
category: "resolution"
description: "Información incorrecta proporcionada"
description_en: "Incorrect information provided"
severity_weight: 0.8
requires_evidence: true
NO_FOLLOW_UP_OFFERED:
category: "resolution"
description: "No se ofreció seguimiento del caso"
description_en: "No follow-up offered"
severity_weight: 0.6
requires_evidence: true
# --- Proceso Utilities ---
COMPLEX_PROCESS:
category: "process"
description: "Proceso excesivamente complejo para el cliente"
description_en: "Excessively complex process for customer"
severity_weight: 0.6
requires_evidence: true
SYSTEM_ERROR:
category: "process"
description: "Error de sistema impidió gestión"
description_en: "System error prevented resolution"
severity_weight: 0.7
requires_evidence: true
METER_ACCESS_ISSUE:
category: "process"
description: "Problemas de acceso al contador"
description_en: "Meter access issues"
severity_weight: 0.5
requires_evidence: true
# --- Emergente ---
OTHER_EMERGENT:
category: "emergent"
description: "Causa emergente (requiere revisión manual)"
description_en: "Emergent cause (requires manual review)"
severity_weight: 0.5
requires_evidence: true
requires_proposed_label: true
# ============================================
# EVENT TYPES (Observable)
# ============================================
event_types:
HOLD_START:
description: "Inicio de espera"
detectable_by: "silence_detector"
HOLD_END:
description: "Fin de espera"
detectable_by: "silence_detector"
TRANSFER:
description: "Transferencia a otro agente/departamento"
detectable_by: "transcript_pattern"
ESCALATION:
description: "Escalación a supervisor"
detectable_by: "transcript_pattern"
SILENCE:
description: "Silencio prolongado (>5 segundos)"
detectable_by: "silence_detector"
threshold_seconds: 5
INTERRUPTION:
description: "Interrupción (overlap de speakers)"
detectable_by: "diarization"
# ============================================
# CHURN RISK DRIVERS - Utilities/Energy
# ============================================
churn_risk:
# --- Insatisfacción con Precio/Factura ---
HIGH_BILL_COMPLAINT:
category: "pricing"
description: "Cliente queja por factura alta"
description_en: "Customer complains about high bill"
severity_weight: 0.8
requires_evidence: true
RATE_DISSATISFACTION:
category: "pricing"
description: "Cliente insatisfecho con la tarifa actual"
description_en: "Customer dissatisfied with current rate"
severity_weight: 0.8
requires_evidence: true
UNEXPECTED_CHARGES:
category: "pricing"
description: "Cliente sorprendido por cargos inesperados"
description_en: "Customer surprised by unexpected charges"
severity_weight: 0.7
requires_evidence: true
# --- Problemas de Servicio ---
REPEATED_OUTAGES:
category: "service"
description: "Cliente reporta cortes de luz recurrentes"
description_en: "Customer reports recurring power outages"
severity_weight: 0.9
requires_evidence: true
SERVICE_QUALITY_ISSUES:
category: "service"
description: "Problemas con calidad del suministro"
description_en: "Issues with supply quality"
severity_weight: 0.8
requires_evidence: true
SLOW_RESPONSE_TO_OUTAGE:
category: "service"
description: "Cliente queja por lentitud en resolver averías"
description_en: "Customer complains about slow outage response"
severity_weight: 0.8
requires_evidence: true
REPEATED_PROBLEMS:
category: "service"
description: "Cliente ha tenido problemas recurrentes"
description_en: "Customer has had recurring problems"
severity_weight: 0.9
requires_evidence: true
# --- Competencia ---
COMPETITOR_MENTION:
category: "competition"
description: "Cliente menciona ofertas de otras comercializadoras"
description_en: "Customer mentions other energy provider offers"
severity_weight: 0.9
requires_evidence: true
COMPARING_RATES:
category: "competition"
description: "Cliente está comparando tarifas del mercado"
description_en: "Customer is comparing market rates"
severity_weight: 0.7
requires_evidence: true
# --- Señales de Baja ---
EXPLICIT_CANCELLATION_INTENT:
category: "cancellation"
description: "Cliente quiere dar de baja el servicio"
description_en: "Customer wants to cancel service"
severity_weight: 1.0
requires_evidence: true
CONTRACT_END_INQUIRY:
category: "cancellation"
description: "Cliente pregunta sobre fin de contrato o penalizaciones"
description_en: "Customer asks about contract end or penalties"
severity_weight: 0.8
requires_evidence: true
PORTABILITY_REQUEST:
category: "cancellation"
description: "Cliente solicita portabilidad a otra comercializadora"
description_en: "Customer requests portability to another provider"
severity_weight: 1.0
requires_evidence: true
# --- Frustración ---
HIGH_FRUSTRATION:
category: "sentiment"
description: "Cliente muestra alta frustración"
description_en: "Customer shows high frustration"
severity_weight: 0.7
requires_evidence: true
THREAT_TO_LEAVE:
category: "sentiment"
description: "Cliente amenaza con cambiar de compañía"
description_en: "Customer threatens to switch providers"
severity_weight: 0.9
requires_evidence: true
# --- Emergente ---
OTHER_EMERGENT:
category: "emergent"
description: "Señal de churn emergente"
description_en: "Emergent churn signal"
severity_weight: 0.5
requires_evidence: true
requires_proposed_label: true
# ============================================
# FCR FAILURE DRIVERS - Utilities/Energy
# ============================================
fcr_failure:
# --- Averías/Incidencias ---
OUTAGE_PENDING:
category: "outage"
description: "Avería pendiente de resolver"
description_en: "Outage pending resolution"
severity_weight: 0.9
requires_evidence: true
TECHNICIAN_VISIT_REQUIRED:
category: "outage"
description: "Requiere visita de técnico"
description_en: "Requires technician visit"
severity_weight: 0.7
requires_evidence: true
OUTAGE_CAUSE_UNKNOWN:
category: "outage"
description: "Causa de avería no determinada"
description_en: "Outage cause not determined"
severity_weight: 0.6
requires_evidence: true
# --- Facturación ---
BILLING_REVIEW_PENDING:
category: "billing"
description: "Revisión de factura pendiente"
description_en: "Bill review pending"
severity_weight: 0.8
requires_evidence: true
REFUND_PENDING:
category: "billing"
description: "Reembolso o abono pendiente"
description_en: "Refund pending"
severity_weight: 0.7
requires_evidence: true
METER_READING_REQUIRED:
category: "billing"
description: "Requiere lectura de contador"
description_en: "Meter reading required"
severity_weight: 0.6
requires_evidence: true
# --- Información ---
MISSING_INFORMATION:
category: "information"
description: "Información incompleta proporcionada"
description_en: "Incomplete information provided"
severity_weight: 0.7
requires_evidence: true
UNCLEAR_NEXT_STEPS:
category: "information"
description: "Cliente no tiene claros los próximos pasos"
description_en: "Customer unclear on next steps"
severity_weight: 0.7
requires_evidence: true
INCORRECT_INFORMATION_GIVEN:
category: "information"
description: "Se proporcionó información incorrecta"
description_en: "Incorrect information was given"
severity_weight: 0.9
requires_evidence: true
# --- Proceso ---
CALLBACK_PROMISED:
category: "process"
description: "Se prometió callback"
description_en: "Callback was promised"
severity_weight: 0.6
requires_evidence: true
ESCALATION_REQUIRED:
category: "process"
description: "Requiere escalación a otro departamento"
description_en: "Requires escalation"
severity_weight: 0.7
requires_evidence: true
CONTRACT_CHANGE_PENDING:
category: "process"
description: "Cambio de contrato pendiente de procesar"
description_en: "Contract change pending processing"
severity_weight: 0.6
requires_evidence: true
SYSTEM_LIMITATION:
category: "process"
description: "Limitación del sistema impidió resolución"
description_en: "System limitation prevented resolution"
severity_weight: 0.7
requires_evidence: true
# --- Emergente ---
OTHER_EMERGENT:
category: "emergent"
description: "Factor FCR emergente"
description_en: "Emergent FCR factor"
severity_weight: 0.5
requires_evidence: true
requires_proposed_label: true
# ============================================
# AGENT SKILL INDICATORS - Utilities/Energy
# ============================================
agent_skills:
positive:
EFFECTIVE_PROBLEM_RESOLUTION:
description: "Resuelve problema eficientemente"
description_en: "Resolves problem efficiently"
skill_area: "problem_solving"
CLEAR_TECHNICAL_EXPLANATION:
description: "Explica temas técnicos de forma clara"
description_en: "Explains technical topics clearly"
skill_area: "technical"
GOOD_RAPPORT:
description: "Construye buena relación con el cliente"
description_en: "Builds good rapport with customer"
skill_area: "communication"
BILLING_EXPERTISE:
description: "Demuestra conocimiento de facturación"
description_en: "Demonstrates billing expertise"
skill_area: "technical"
ACTIVE_LISTENING:
description: "Escucha activa al cliente"
description_en: "Active listening to customer"
skill_area: "communication"
EMPATHY_SHOWN:
description: "Muestra empatía ante problemas"
description_en: "Shows empathy for problems"
skill_area: "soft_skills"
CLEAR_COMMUNICATION:
description: "Comunicación clara y estructurada"
description_en: "Clear and structured communication"
skill_area: "communication"
PROACTIVE_SOLUTIONS:
description: "Ofrece soluciones proactivamente"
description_en: "Proactively offers solutions"
skill_area: "problem_solving"
OUTAGE_HANDLING:
description: "Gestiona averías efectivamente"
description_en: "Handles outages effectively"
skill_area: "technical"
RETENTION_SKILLS:
description: "Demuestra habilidad de retención"
description_en: "Demonstrates retention skills"
skill_area: "sales"
improvement_needed:
POOR_PROBLEM_RESOLUTION:
description: "No resuelve el problema adecuadamente"
description_en: "Doesn't resolve problem adequately"
skill_area: "problem_solving"
CONFUSING_EXPLANATION:
description: "Explicaciones confusas o técnicas"
description_en: "Confusing or overly technical explanations"
skill_area: "technical"
LACK_OF_RAPPORT:
description: "No construye relación con el cliente"
description_en: "Doesn't build rapport with customer"
skill_area: "communication"
BILLING_KNOWLEDGE_GAPS:
description: "Gaps en conocimiento de facturación"
description_en: "Gaps in billing knowledge"
skill_area: "technical"
NOT_LISTENING:
description: "No escucha al cliente"
description_en: "Doesn't listen to customer"
skill_area: "communication"
LACK_OF_EMPATHY:
description: "Falta de empatía ante problemas"
description_en: "Lack of empathy for problems"
skill_area: "soft_skills"
CONFUSING_COMMUNICATION:
description: "Comunicación confusa o desorganizada"
description_en: "Confusing or disorganized communication"
skill_area: "communication"
REACTIVE_ONLY:
description: "Solo reactivo, no busca soluciones"
description_en: "Only reactive, doesn't seek solutions"
skill_area: "problem_solving"
POOR_OUTAGE_HANDLING:
description: "Gestión deficiente de averías"
description_en: "Poor outage handling"
skill_area: "technical"
NO_RETENTION_EFFORT:
description: "No intenta retener al cliente"
description_en: "No retention effort"
skill_area: "sales"
# ============================================
# CALL OUTCOMES - Utilities/Energy
# ============================================
call_outcomes:
# --- Averías ---
- OUTAGE_REPORTED
- OUTAGE_RESOLVED
- OUTAGE_ESCALATED
- TECHNICIAN_SCHEDULED
# --- Facturación ---
- BILLING_INQUIRY_RESOLVED
- BILLING_DISPUTE_OPENED
- PAYMENT_ARRANGEMENT_MADE
- REFUND_PROCESSED
# --- Contratos ---
- RATE_CHANGE_COMPLETED
- CONTRACT_RENEWED
- SERVICE_UPGRADED
- SERVICE_DOWNGRADED
# --- Retención ---
- CANCELLATION_SAVED
- CANCELLATION_COMPLETED
- PORTABILITY_INITIATED
# --- General ---
- INQUIRY_RESOLVED
- INQUIRY_UNRESOLVED
- CALLBACK_SCHEDULED
- TRANSFER_OUT
- UNKNOWN
# ============================================
# VALIDATION RULES
# ============================================
validation:
min_evidence_spans: 1
confidence_thresholds:
high: 0.8
medium: 0.6
low: 0.4
reject: 0.3
reject_low_confidence: true
emergent:
require_proposed_label: true
require_evidence: true
exclude_from_main_rca: true
Reference in New Issue View Git Blame Copy Permalink