# 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.toml` instead 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.