# 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`](../../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`](docs/build_spec_v1.md).

## Run

```bash
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:

```bash
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.