# 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.