Robert Helewka
a967f73d09
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.
108 lines
5.2 KiB
Markdown
108 lines
5.2 KiB
Markdown
# Study Pattern v1.0.0
|
|
|
|
How Palladium ships **Studies**: dated reproductions of a published base document —
|
|
a Forrester TEI study or similar — personalized to a client as an overlay. A Study is
|
|
a **master**: the anchor is public/published data, the master stays client-clean, and
|
|
client personalization happens in an engagement copy outside this repo. References:
|
|
[`studies/202512_TEI_Genesys_CX_Cloud/`](../studies/202512_TEI_Genesys_CX_Cloud/) and
|
|
[`studies/202602_TEI_Amazon_Connect/`](../studies/202602_TEI_Amazon_Connect/)
|
|
(both package `teicalc`).
|
|
|
|
## 🐾 Red Panda Approval™
|
|
|
|
This pattern follows Red Panda Approval standards (see `CLAUDE.md` for the rubric).
|
|
|
|
**Audience note:** written to be loaded whole by an LLM agent building or modifying a
|
|
study. This document holds what studies ADD to the
|
|
[Mercury Notebook Deliverable Pattern](Mercury_Notebook_Pattern_V1-00.md) — shared
|
|
mechanics live there and are not restated. `CLAUDE.md` takes precedence where
|
|
documents disagree.
|
|
|
|
**Status note — read this before "fixing" a study:** this pattern is grounded in the
|
|
TEI twins **as they are today**: math and anchors in the `.py` engine, hand-authored
|
|
notebooks, no tagged-cell taxonomy. The notebook-first evolution — client data in an
|
|
`engagement-data` cell, tagged content cells, the Assessment Pattern's cell taxonomy —
|
|
**lands with the first study redesign** (a recorded identified opportunity in
|
|
`CLAUDE.md`), not by piecemeal edits. Until then the repo-level structural suite
|
|
grandfathers the study notebooks by name, and their current shape is the correct
|
|
shape. `studies/202607_CTM_GenesysCX/` is a grandfathered real-client engagement
|
|
study — frozen; see `CLAUDE.md` § Known liabilities.
|
|
|
|
---
|
|
|
|
## What a Study is
|
|
|
|
| | **Study** | Assessment |
|
|
|---|---|---|
|
|
| Reproduces | a **dated publication** (TEI) or signed engagement | — |
|
|
| Naming | `YYYYMM_TEI_Vendor_Product` / `YYYYMM_Client_Engagement` | undated |
|
|
| Anchor | the publication's composite, **verbatim** | the instrument's content |
|
|
| "Numbers" | dollars — NPV / ROI / payback | qualitative state |
|
|
| Client data | overlay rescale on the anchor | `engagement-data` cell |
|
|
|
|
The `YYYYMM_` prefix is the **publication/engagement date** (e.g. `202512_` = the
|
|
December 2025 Forrester study), not the date you worked on it — a Study is a snapshot
|
|
of a dated document and stays dated.
|
|
|
|
## Verbatim anchor + contracted overlay
|
|
|
|
The heart of a Study (mechanics in the Mercury Pattern, *Recommended Practices*):
|
|
|
|
- `anchor.py` holds the publication's tables as `*_VERBATIM` constants — **NEVER
|
|
edited**. The reproduction is only worth anything if the anchor is the exact
|
|
published record.
|
|
- `overlay.py` layers client personalization over the anchor — in the current twins, a
|
|
🟡 first-order linear rescale by client drivers (agents / contacts / growth):
|
|
"the composite at your size", never presented as "your TEI".
|
|
- Notebooks read through the `anchor()` helper so the walk *published → personalized*
|
|
stays explicit and auditable on stage.
|
|
|
|
## The reproduction gate
|
|
|
|
A Study's gate (Mercury Pattern §4) MUST pin the **published headline numbers** —
|
|
the reproduction is the smoke test:
|
|
|
|
- Amazon Connect twin: NPV **$78,713,715**, ROI **342%**, payback **<6 months**.
|
|
- Genesys CX Cloud twin: NPV **$10,783,468**, ROI **266%**.
|
|
|
|
Plus the **composite-scale identity**: the overlay at the composite's own drivers must
|
|
reproduce the anchor exactly (rescale(1.0) == anchor) — the proof the personalization
|
|
layer adds nothing at scale 1.
|
|
|
|
## Confidentiality posture
|
|
|
|
- The **published source PDF** (the Forrester study) is public and MAY live in the
|
|
study's `docs/` — it is the one exception to the binary-documents block in
|
|
`.gitignore`: add it with `git add -f` and name the source in the commit message.
|
|
- Everything else follows `CLAUDE.md` § Confidentiality: masters client-clean, client
|
|
personalization only in an engagement copy outside the repo, and NEVER commit client
|
|
documents (SOWs, quotes, NDA'd vendor decks). The CTM study predates this rule and
|
|
is grandfathered — do not use it as precedent.
|
|
|
|
## Layout & testing
|
|
|
|
Layout and packaging are the Mercury Pattern's (self-contained `teicalc`-style engine,
|
|
per-study venv, whole toolchain as core deps). Testing is the standard four layers
|
|
plus repo-level layer 0; a Study's engine pins carry BOTH the verbatim record and the
|
|
overlay, so neither can drift:
|
|
|
|
```
|
|
tests/test_anchor.py # the published tables, pinned line by line
|
|
tests/test_overlay.py # rescale identity at composite scale + spot rescales
|
|
tests/test_scenarios.py # scenario framing over the overlay
|
|
tests/test_model.py # finance primitives (NPV, payback) hand-checked
|
|
tests/test_staging.py # stage/backstage
|
|
```
|
|
|
|
## Variants
|
|
|
|
The Mercury Pattern's variants map onto Studies as:
|
|
|
|
- **Variant 4 — TEI composite reproduction** — the canonical Study (both twins).
|
|
- **Variant 1 — corrected/pressure-tested business case** — engagement-study form
|
|
(CTM's `ctm_business_case_corrected`): vendor claims verbatim, omitted costs added.
|
|
- **Variant 2 — scenario notebook on a thin module** — a second question over the same
|
|
engine (CTM's `migration_wfm`).
|
|
- **Variant 3 — exploratory calculator** — pre-anchor what-if surface that graduates
|
|
into Variant 1 as facts arrive.
|