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:
2026-07-31 16:16:07 +00:00
parent 53c069fddb
commit a967f73d09
61 changed files with 4881 additions and 4257 deletions

View 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, 48 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.