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.
This commit is contained in:
107
docs/Study_Pattern_V1-00.md
Normal file
107
docs/Study_Pattern_V1-00.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user