palladium/studies/202607_CX_AI_Diagnostic/README.md

CX AI Advisory Diagnostic

Facilitator's cockpit for the CX AI Advisory diagnostic workshop (Mercury Notebook Pattern — see docs/Mercury_Notebook_Pattern_V1-00.md). Captures capability scores across 12 competencies in four dimensions (Strategy & Value, Foundations, Delivery, Sustain), ingests the client's operational baseline, computes value-at-stake bounded by capability gaps, and exports a structured engagement record.

Single facilitator, live half-day workshop, 4–8 client participants. Not for client self-service, unattended use, or deployment. Specification: docs/build_spec_v1.md.

Run

python -m venv .venv && .venv/bin/pip install -e ".[dev]"   # once
source .venv/bin/activate

mercury --working-dir .        # the workshop stage (serve from study root)
jupyter lab                    # analyst view (backstage)
pytest                         # engine pins
python scripts/export_report.py     # exports/diagnostic.{html,md}

The notebook is generated — edit cell sources in scripts/build_notebook.py, then:

python scripts/build_notebook.py
jupyter nbconvert --to notebook --execute --inplace notebooks/diagnostic.ipynb

Layout

diaglib/            # THE study package — all math and contracts
│   models.py       #   pydantic models: engagement data + config schema
│   config.py       #   configs/*.yaml loading, base+overlay merge
│   scoring.py      #   score aggregation, participants, assembly
│   value_math.py   #   drivers, capping, trapped value, unlock sequence
│   visuals.py      #   plotly builders (house chrome)
│   export.py       #   exports/{engagement_id}.json + .csv
│   staging.py      #   stage/backstage detection (pattern verbatim)
configs/
│   base.yaml       #   the instrument: 12 competencies, capping heuristic
│   contact_center.yaml       # value drivers + unlock costs (🟡 ranges)
│   financial_services.yaml   # stub — scoring only until drivers added
notebooks/diagnostic.ipynb    # the deliverable (generated)
scripts/            # build_notebook.py · export_report.py
tests/              # hand-checked pins for every engine number
exports/            # per-engagement JSON/CSV + report sources (gitignored)

Design decisions (deviations from the build spec, both additive)

• Unlock moves are tier lifts of the binding set (competency_ids plural). When several foundations tie at the weakest level, lifting one alone honestly unlocks nothing — the set is the move, costs summed, weeks = longest parallel workstream.
• "One screen per competency" is a Now scoring selector, not a Next button — Mercury's reactivity model makes stateless buttons awkward, and the selector adds random access for revisits. All score sliders stay live in the sidebar.
• requirements.txt is replaced by pyproject.toml per the pattern (pip install -e . provisions everything).

Before using with a real client

The value-driver ranges and unlock costs in contact_center.yaml are 🟡 placeholders (build spec §12): back them with cited public sources or "based on N engagements" framing, and tune cost_per_replacement_default per engagement.