CX Discovery Notebook

studies/202607_CX_Discovery_Workshop/README.md

@@ -0,0 +1,83 @@
+# 202607 — CX Exploration & Discovery Workshop
+
+A **live facilitation aid** for a CX discovery session, built on the
+[Mercury Notebook Deliverable Pattern](../../docs/Mercury_Notebook_Pattern_V1-00.md).
+Unlike the TEI business-case studies, this deliverable computes no dollars —
+its "numbers" are **topic status and progress**. The Mercury stage is the
+visual you share on a call or in a workshop while you work through the
+questions; the question script and captured notes live backstage and export
+as LLM input for the survey write-up or a downstream business case.
+
+## What the client sees (the stage)
+
+A calm **topic board**: each topic, its one-line scope, a status glyph, and —
+for the topic under discussion — a **live sub-topic checklist**, above a
+**progress bar** ("3/8 topics complete"). No wall of questions: you ask those.
+
+![board preview](docs/board_preview.png)
+
+You drive it from the sidebar — a **status** selector and a **notes** box per
+topic, plus a **checkbox** per sub-topic. As the conversation moves you set a
+topic *In progress*, tick sub-topics as you cover them, mark it *Complete* (or
+*Skipped*), and jot answers. Every change re-renders the board and progress bar
+(Mercury re-runs the cells below the widgets).
+
+## What you work from (backstage)
+
+JupyterLab and the exports carry the **facilitator question script** (all 95
+prompts, grouped by topic → sub-topic) and the **captured-session appendix**
+(status + notes as a markdown table and one JSON block). Neither shows on the
+Mercury stage. The 8 topics / 26 sub-topics / ~110-minute agenda are the
+structured form of the source survey.
+
+## Layout
+
+```
+discoverylib/           # the engine — all content & logic
+  topics.py             #   the topic bank (verbatim anchor from the survey)
+  session.py            #   status vocabulary, progress, checklist, export payload
+  staging.py            #   stage/backstage detection (copied verbatim)
+notebooks/cx_discovery.ipynb   # the deliverable (generated — see below)
+scripts/
+  build_notebook.py     #   regenerates the notebook from cell sources
+  export_report.py      #   nbconvert → exports/*.html + *.md
+tests/                  # engine pins + stage/backstage test
+docs/cx_discovery_survey.md    # source survey (the original cxxm.md)
+exports/                # generated report sources
+```
+
+## The notebook is generated
+
+The notebook wires ~42 Mercury widgets (a status selector + notes box per
+topic, a checkbox per sub-topic), all derived from the topic bank so they can't
+drift from `discoverylib`. Rather than hand-maintain that JSON, the notebook is
+built from readable cell sources in
+[`scripts/build_notebook.py`](scripts/build_notebook.py):
+
+```bash
+python scripts/build_notebook.py      # regenerate after editing a cell
+```
+
+Edit facilitation *content* (topics, sub-topics, prompts, scope, minutes) in
+[`discoverylib/topics.py`](discoverylib/topics.py) — not in the notebook.
+
+## Run
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+mercury --working-dir .                # serve the stage (share this screen)
+jupyter lab                            # analyst / facilitator view
+pytest                                 # engine pins + stage/backstage
+jupyter nbconvert --to notebook --execute --inplace notebooks/cx_discovery.ipynb   # gate
+python scripts/export_report.py        # exports/*.html + *.md for the LLM handoff
+```
+
+## Extending
+
+New or reshaped discovery content is a `discoverylib/topics.py` edit, a test
+pin (`tests/test_topics.py` recounts, `tests/test_session.py` for new logic),
+then `python scripts/build_notebook.py`. Add a topic and the sidebar controls,
+board, checklist, script, gate, and export all pick it up — because they're all
+generated from the bank.