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

4.7 KiB

Raw Permalink Blame History

CX AI Advisory Diagnostic — Build Spec v1.0

Source record for this study (received 2026-07-19, owner Robert Helewka). Kept verbatim in intent; §2 layout was adapted to the Mercury Notebook Pattern (study package diaglib/, generated notebook, pyproject.toml instead of requirements.txt) — see README for the deviations log.

Purpose: Facilitator's cockpit for the CX AI Advisory diagnostic workshop. Captures capability scores across 12 competencies, ingests client operational baseline, computes value-at-stake bounded by capability gaps, exports structured data.

Users: Single facilitator (Robert) running a live half-day workshop with 4–8 client participants.

NOT for: Client self-service, unattended use, public deployment, SaaS.

1. Stack

Python 3.11+, Jupyter Notebook, Mercury (mljar-mercury), pandas, plotly (matplotlib fallback), pydantic, PyYAML. Runs locally. No server, no auth, no database.

2. Structure

Study package (diaglib/) with models / scoring / value_math / visuals / export; configs/ (base + industry overlays); one deliverable notebook; gitignored exports/.

3. Data model

Engagement (id client_slug_YYYY-MM-DD, client, industry config, facilitator, date, participants, baseline, scores, computed value, notes) · Participant (name, role, function cx|it|ops|finance|other) · OperationalBaseline (annual_contact_volume, blended_cost_per_contact, agent_headcount, annual_attrition_rate, current_containment_rate, average_handle_time_seconds; optional csat_baseline, revenue_at_risk; per-field confidence known|estimated|unknown) · CompetencyScore (competency, dimension, score 1–5, evidence line, scorer role, timestamp) · ValueAtStake (theoretical annual low/high, realizable 18-mo low/high, trapped low/high, binding constraints, unlock sequence) · UnlockMove (competencies, level lift, cost range, weeks, value unlocked range).

4. Configs

base.yaml — 12 competencies across 4 dimensions, each with description, failure vignette, level descriptors 1–5; capping heuristic (weakest foundational score → realization band): 1: 0.00–0.15, 2: 0.25–0.40, 3: 0.50–0.65, 4: 0.65–0.85, 5: 0.80–1.00; foundational competencies: process_discovery, data_readiness, technical_architecture.

contact_center.yaml — value drivers: deflection/containment lift (+15–35 pts × volume × cost/contact), AHT reduction (15–25%), attrition reduction (10–20%, $15K/replacement default); unlock costs per level-lift per foundational competency (sparse OK).

financial_services.yaml — stub for MVP.

5. Notebook sections

0 Setup (hidden) · 1 Engagement form · 2 Operational baseline with confidence flags · 3 Capability scoring, one screen per competency (name, description, vignette, level descriptors; score + evidence) · 4 Live analysis · 5 Visuals (heatmap, value bands, trapped/realizable split, unlock chart) · 6 Export button → JSON + CSV.

6. Value math

theoretical = Σ driver ranges → realization band from weakest foundational score → realizable_18mo = theoretical × factor × 1.5 → trapped = theoretical − realizable run-rate → binding constraints = all foundational competencies at the weakest score → unlock sequence: lift binding constraints one level, recompute factor, up to 3 moves.

Guard rails: all outputs are ranges; explicit warnings on 🔴-unknown inputs; money display ≤ 2 significant figures.

7–8. Visuals & exports

Room-facing interactive plotly. Heatmap 4×3 with scores + evidence hover; horizontal value bands (theoretical light / realizable dark, trapped labeled); split chart; unlock cost-vs-value chart. exports/{engagement_id}.json (full Engagement — source of truth) + .csv (one row per competency: engagement_id, client_name, industry, workshop_date, competency_id, dimension, score, evidence, is_foundational, is_binding_constraint).

9. Non-goals (MVP)

No auth · no multi-stakeholder independent scoring (v1.1) · no LLM recommendations · no PDF · no history dashboard · no cloud · no SaaS · no client-facing scoring.

10. Acceptance

Launch Mercury → contact_center → new engagement; enter client info + 4–8 participants; six baseline numbers with confidence flags; score all 12 competencies with evidence; four visuals render live; Export writes valid JSON + CSV; (nice-to-have) reload saved JSON; edit YAML ranges → recomputed outputs. Done = end-to-end in under 90 minutes with mock inputs and sensible output.

12. Open questions (Robert)

Benchmark citations for §4 ranges before first real client (Alan's research subagent offer pending go-ahead).
$15K cost-per-replacement default — config-driven, tune per engagement.
Multi-stakeholder scoring — v1.1 if workshops routinely score independently; don't build now.

4.7 KiB Raw Permalink Blame History Unescape Escape