Robert Helewka
53c069fddb
Rewrite the CX Discovery Workshop README to reflect the architecture shift where content lives in the notebook's `topic-bank` cell rather than in `discoverylib/topics.py`. The library now holds code only, the notebook is the deliverable (no longer generated via build_notebook.py), and tests pin content read directly from the notebook. Update layout, run, and extending sections accordingly.
4.5 KiB
202607 — CX Exploration & Discovery Workshop
A live facilitation aid for a CX discovery session, built on the Mercury Notebook Deliverable Pattern. 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.
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.
Where the content lives: in the notebook
The topic bank — every topic, sub-topic, and facilitator prompt — lives in
the topic-bank cell of
notebooks/cx_discovery.ipynb (the code cell
tagged topic-bank, right under the title). Content is edited there, in
Jupyter — never in a .py file. It is the study's verbatim anchor: wording
tracks the source survey
docs/cx_discovery_survey.md (the original
cxxm.md), and the key slugs are stable identities the sidebar widgets,
captured notes, and JSON export all key off — never renumber or rename them
casually. The cell's own comment block carries the full editing rules.
discoverylib/ holds code only: the Topic/SubTopic schema, the
status vocabulary, and the session engine — every engine function takes the
bank as its first argument. The ~42 sidebar widgets are built by a runtime
loop over TOPICS, so board, checklist, script, gate, and export all pick up
a content edit automatically. The test suite reads the tagged cell straight
out of the notebook (no kernel) and pins the content, so pytest guards the
bank exactly as shipped.
Layout
notebooks/cx_discovery.ipynb # THE deliverable — content (topic-bank cell) + presentation
discoverylib/ # the engine — code only, no content
session.py # Topic/SubTopic schema, status vocabulary, progress, export payload
staging.py # stage/backstage detection (copied verbatim)
scripts/export_report.py # nbconvert → exports/*.html + *.md
tests/ # content pins (read from the notebook) + engine pins + staging test
docs/cx_discovery_survey.md # source survey (the original cxxm.md)
exports/ # generated report sources
Run
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 # content pins + 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 an edit to the notebook's topic-bank
cell in JupyterLab, then:
- Re-run the notebook — the in-notebook gate recounts the bank (topics / sub-topics / prompts / key order / agenda minutes); update its pins if the change is deliberate.
pytest—tests/test_topics.pypins the same shape from outside the kernel; re-pin the counts there too.
Add a topic and the sidebar controls, board, checklist, script, gate, and
export all pick it up — they're all derived from TOPICS at runtime. New
logic (not content) goes in discoverylib/session.py with pins in
tests/test_session.py.