palladium/docs/Study_Pattern_V1-00.md

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/ and 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 — 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.