4.7 KiB
CX AI Advisory Diagnostic — Build Spec v1.0
Source record for this study (received 2026-07-19, owner Robert Helewka). Kept verbatim in intent; §2 layout was adapted to the Mercury Notebook Pattern (study package
diaglib/, generated notebook,pyproject.tomlinstead of requirements.txt) — see README for the deviations log.
Purpose: Facilitator's cockpit for the CX AI Advisory diagnostic workshop. Captures capability scores across 12 competencies, ingests client operational baseline, computes value-at-stake bounded by capability gaps, exports structured data.
Users: Single facilitator (Robert) running a live half-day workshop with 4–8 client participants.
NOT for: Client self-service, unattended use, public deployment, SaaS.
1. Stack
Python 3.11+, Jupyter Notebook, Mercury (mljar-mercury), pandas, plotly (matplotlib fallback), pydantic, PyYAML. Runs locally. No server, no auth, no database.
2. Structure
Study package (diaglib/) with models / scoring / value_math / visuals /
export; configs/ (base + industry overlays); one deliverable notebook;
gitignored exports/.
3. Data model
Engagement (id client_slug_YYYY-MM-DD, client, industry config,
facilitator, date, participants, baseline, scores, computed value,
notes) · Participant (name, role, function cx|it|ops|finance|other) ·
OperationalBaseline (annual_contact_volume, blended_cost_per_contact,
agent_headcount, annual_attrition_rate, current_containment_rate,
average_handle_time_seconds; optional csat_baseline, revenue_at_risk;
per-field confidence known|estimated|unknown) · CompetencyScore
(competency, dimension, score 1–5, evidence line, scorer role,
timestamp) · ValueAtStake (theoretical annual low/high, realizable
18-mo low/high, trapped low/high, binding constraints, unlock sequence)
· UnlockMove (competencies, level lift, cost range, weeks, value
unlocked range).
4. Configs
base.yaml — 12 competencies across 4 dimensions, each with description, failure vignette, level descriptors 1–5; capping heuristic (weakest foundational score → realization band): 1: 0.00–0.15, 2: 0.25–0.40, 3: 0.50–0.65, 4: 0.65–0.85, 5: 0.80–1.00; foundational competencies: process_discovery, data_readiness, technical_architecture.
contact_center.yaml — value drivers: deflection/containment lift (+15–35 pts × volume × cost/contact), AHT reduction (15–25%), attrition reduction (10–20%, $15K/replacement default); unlock costs per level-lift per foundational competency (sparse OK).
financial_services.yaml — stub for MVP.
5. Notebook sections
0 Setup (hidden) · 1 Engagement form · 2 Operational baseline with confidence flags · 3 Capability scoring, one screen per competency (name, description, vignette, level descriptors; score + evidence) · 4 Live analysis · 5 Visuals (heatmap, value bands, trapped/realizable split, unlock chart) · 6 Export button → JSON + CSV.
6. Value math
theoretical = Σ driver ranges → realization band from weakest foundational score → realizable_18mo = theoretical × factor × 1.5 → trapped = theoretical − realizable run-rate → binding constraints = all foundational competencies at the weakest score → unlock sequence: lift binding constraints one level, recompute factor, up to 3 moves.
Guard rails: all outputs are ranges; explicit warnings on 🔴-unknown inputs; money display ≤ 2 significant figures.
7–8. Visuals & exports
Room-facing interactive plotly. Heatmap 4×3 with scores + evidence
hover; horizontal value bands (theoretical light / realizable dark,
trapped labeled); split chart; unlock cost-vs-value chart.
exports/{engagement_id}.json (full Engagement — source of truth) +
.csv (one row per competency: engagement_id, client_name, industry,
workshop_date, competency_id, dimension, score, evidence,
is_foundational, is_binding_constraint).
9. Non-goals (MVP)
No auth · no multi-stakeholder independent scoring (v1.1) · no LLM recommendations · no PDF · no history dashboard · no cloud · no SaaS · no client-facing scoring.
10. Acceptance
Launch Mercury → contact_center → new engagement; enter client info + 4–8 participants; six baseline numbers with confidence flags; score all 12 competencies with evidence; four visuals render live; Export writes valid JSON + CSV; (nice-to-have) reload saved JSON; edit YAML ranges → recomputed outputs. Done = end-to-end in under 90 minutes with mock inputs and sensible output.
12. Open questions (Robert)
- Benchmark citations for §4 ranges before first real client (Alan's research subagent offer pending go-ahead).
- $15K cost-per-replacement default — config-driven, tune per engagement.
- Multi-stakeholder scoring — v1.1 if workshops routinely score independently; don't build now.