feat: add master notebook library scaffolding and review tooling
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.
This commit is contained in:
74
assessments/CX_AI_Diagnostic/README.md
Normal file
74
assessments/CX_AI_Diagnostic/README.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user