Files

Robert Helewka a967f73d09 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.

2026-07-31 16:16:07 +00:00

3.2 KiB

Raw Blame History

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.

3.2 KiB Raw Blame History Unescape Escape

CX AI Advisory Diagnostic

Run

Layout

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

Before using with a real client

3.2 KiB

Raw Blame History