Robert Helewka
a967f73d09
Add CLAUDE.md defining the Palladium master notebook conventions and Red Panda Approval criteria, plus a review-notebook slash command for LLM-driven notebook review. Expand .gitignore to block client/engagement documents and generated exports, keeping masters client-clean while allowing text/image sources. Normalize slider widget numeric values from floats to integers in notebook JSON.
75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
# 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.
|