Measurement Schema — Reader's Guide¶

Purpose: Plain-language explainer for the measurement schema work. Written for people who want to understand what was built, why it matters, and what decisions still need to be made — without learning the shorthand.

Companion to: measurement-schema.md (the formal canonical doc, full of shorthand) and ../archive/measurement-schema-working.md (the iteration history, archived).

Interactive schematic

📊 Open the interactive measurement-schema explorer ↗ — a clickable, searchable schematic of every primitive with definition drawers, layer filters, and a pipeline overview (opens in a new tab). Hand-built for sharing with the team; best for exploring. This guide is best for reading.

What this whole thing is for¶

Pulse measures how people make decisions — their reasoning style, calibration, persuadability, biases, and trust patterns. The measurement happens in many specific places in the codebase: capturing raw player actions, computing signals from rationale text, aggregating per-player profiles, exposing profiles to agents like Hermes or ChatGPT.

Until this work, all those measurement pieces existed but weren't systematically enumerated. They were spread across ADRs and code. Nobody had written down the complete list of "every primitive Pulse uses to measure judgment" or how the pieces fit together architecturally.

This work did that enumeration — exhaustively. Then it stress-tested the result against synthetic and real player profiles to confirm the schema actually holds.

Why it matters:

Multi-domain expansion (ADR-074) is on the roadmap. Pulse is positioning as "the judgment layer for any AI." For that to work, the measurement architecture needs to support any domain — not just governance. The schema work confirms the architecture is ready: adding new domains is corpus work, not architecture rebuild.
Onboarding new collaborators (Amin, Cici, James contributing via PRs) gets faster when the measurement architecture is documented. They can read the canonical doc and understand what's there without spelunking through code.
Product decisions (what to ship next, what to defer) get clearer when you can see the schema's gaps mapped to specific closure shapes. The schema work surfaced 5 closure paths that map to specific product/engineering work.

The big picture in plain language¶

The schema has four layers that pass data forward, plus a fifth category for things that emerge from player behavior.

flowchart LR
  C["<b>① Capture</b><br/>14 · C1–C14<br/><i>raw player actions</i>"]
  E["<b>② Extraction</b><br/>22 · E5–E22, E_*<br/><i>computed signals</i>"]
  A["<b>③ Aggregation</b><br/>14 · A1–A14<br/><i>per-player roll-ups</i>"]
  X["<b>④ Exposure</b><br/>11 · X1–X11<br/><i>what users & agents see</i>"]
  M["<b>⑤ Measured outcomes</b><br/>9 · M1–M9<br/><i>emergent properties</i>"]
  C --> E --> A --> X
  E -.-> M
  A -.-> M

Solid arrows = data passes forward. Dashed = Layer 5 emerges from combining signals across many games, not from a single forward pass. 70 primitives total.

Layer 1 — Capture (what gets written to the database)¶

When a player plays a round, Pulse records: - Which option they picked - The rationale text they typed - Their conviction (1–5) - How long they took to decide - Optional reaction after the AI reveal ("gets me" / "off track" / "interesting") - Optional note after the reveal - In multiplayer: who they predicted others would pick, how confident, and whether they stood by their choice after discussion - For Hermes/agent users: each time the agent reads their profile, whether they asked "why," and any feedback rating

That's it for capture. 14 distinct types of records. The names in the formal doc are C1 through C14.

Layer 2 — Extraction (what gets computed from raw captures)¶

From the raw captures above, Pulse computes signals. This is where the 14 behavioral signals from ADR-024 live, plus 8 others. Examples:

Reasoning style — classified by Claude from rationale text (consequentialist / intuitive / principled-deductive / eliminative / analogical / systems-thinking)
Attention focus — what kinds of details the player notices (political / temporal / ethical / financial / technical / interpersonal)
Confidence calibration — does high conviction match high accuracy?
Persuadability — do they stand or revise under social pressure?
Pragmatic routing — do they decline binary framings and propose third options?
Ideal-actual reference frequency (E14) — do they explicitly name distance between "what I'd ideally do" and "what I actually do"? (Renamed from "self-aware aspiration gap" per the rename in §6 — neutral name, since the same pattern reads as calibration or verbal hedging.)

22 extractions total. Some run at the moment a round is recorded (frozen on the row, like the AI twin's prediction or the driver classification). Others compute on demand when someone asks for the player's profile.

The names are E5–E22 plus a few E_ prefixed ones for the write-time computations.

Layer 3 — Aggregation (per-player roll-ups)¶

Per-player summaries that combine extractions across all their games:

Sync score (lifetime)
Three Sync Dimensions — Accuracy / Coverage / Readability (the score breakdown that ADR-045 ships)
Category patterns — distribution of reasoning styles per category (governance, team dynamics, etc.)
Signal aggregates — per-signal accumulated stats (reasoning style distribution, attention distribution, calibration stats, etc.)
Agent-side metrics — rate of "why" requests, feedback engagement, feedback positivity

14 aggregations total. Names are A1–A14.

Layer 4 — Exposure (what gets shown externally)¶

How aggregations reach users and agents: - Sync score headline on the Twin/share pages - Three Sync Dimensions on the Play screen - Behavioral attention signals card on insights page - Agent context block — the prose summary Hermes uses to represent the player - MCP tools that agents call to get the profile

11 surfaces total. Names are X1–X11.

Layer 5 — Measured outcomes (emergent player × system properties)¶

These aren't directly written to the database. They emerge when you combine signals across many games: - Identity load — how much the player's identity is at stake in a decision - Domain confidence asymmetry — confident in some domains, deferent in others - User trust state with the agent — how trusting/distrusting/calibrating the player is toward Hermes - Frame-restructuring tendency — how often the player declines the binary - Calibration drift — is calibration improving or degrading over time?

9 outcomes. Names are M1–M9.

Glossary — every acronym and shorthand decoded¶

Letters / numbers¶

Prefix	Meaning
`C1`–`C14`	Capture primitives (Layer 1)
`E_*`, `E5`–`E22`	Extraction primitives (Layer 2)
`A1`–`A14`	Aggregation primitives (Layer 3)
`X1`–`X11`	Exposure primitives (Layer 4)
`M1`–`M9`	Measured outcomes (Layer 5)
`cube-C1`, `cube-C2`	The cube doc's content-layer axes (cost categories; expertise-requirement). Different namespace from schema's `C1`–`C14`.
`Q1`–`Q5`, `Q4a`–`Q4d`	Parked questions (deferred decisions)
`OQ-*`	Open questions (active under-questions)
`SS-1`	One specific open question that was promoted to a convention

Method terms¶

Term	Meaning
Swing	A stress test where you construct a specific scenario or profile pair and ask "does the schema correctly discriminate this?" If not, you refine.
Repeat	Re-running an earlier swing against the now-updated schema to check if it still holds.
Decomposition	Applying the schema to a real or synthetic player profile and tagging every primitive. Validates schema covers real data.
Promotion	Moving a finding from "tentative" to "canonical" once enough evidence accumulates (typically 3+ confirmations).
Closure path	A specific piece of work that closes a gap. Usually has 3 stages: gap surfaced → closure named → external implementation.

Key concepts¶

Term	Meaning
SPOF	Single point of failure. Used to flag central extractions (mainly `E_classify_driver`, the Claude call that labels reasoning style) whose contamination or missingness ripples through 40% of downstream signals.
Principle 7	The schema-level discipline that any aggregation, extraction, or prose layer consuming a "final-state" capture should also check whether co-captured "process" information would discriminate better. (E.g., when reading reactions, also read the free-text note. When reading choices, also read the rationale text.)
Convention 6	The discipline that every aggregation carries a sample-size denominator. If N is low, downstream surfaces should mark it tentative.
Convention 7	The discipline that state-sensitive outcomes (calibration drift, trust state) carry "as of [date]" annotations when surfaced in static text that won't refresh.
Three-category gap synthesis	The finding that schema gaps cluster into three kinds: architectural (need new primitives — only one occupant, Q5), aggregation (existing primitives under-utilized), and exposure (downstream interpretation issues).
Architectural independence	The finding that the schema's design dimensions (closure paths, measured outcomes, signals, conventions) compose without interacting. Implementing one doesn't require coordinating with another.

Other terms encountered¶

Term	Meaning
Hermes	Internal codename for the Pulse agent skill (SKILL.md running in Claude.ai / Claude Code). Going forward: prefer "the Pulse agent" or "the agent."
games_played vs games_analyzed	`games_played` counts session completions. `games_analyzed` counts individual scenarios processed for profile updates. One session can contain multiple scenarios, so `games_analyzed` is typically larger. Convention 6's sample-size annotations use `games_analyzed`.
E14 (ideal-actual reference frequency) absence as a signal	Most players don't articulate ideal-vs-actual gaps in their rationale; E14 fires for a minority. The absence of E14 is itself meaningful — combined with low E18 (self-awareness) it suggests weak meta-cognition, which the light-paper governance algorithm can use as a trust-tier modifier.

People and profile shorthand¶

Shorthand	Meaning
CoachJ	Jonathan's profile (the most-resolved real data point — 83 games).
Synthetic profile letters (BA, ON, LMA, MO, SP, PU, HT, DT, DA, DU, HG, FS, DS, CB, PR, MD, DR, DN, NS, CAPR, RE, RND, SPMO, MAX, CMS, VHN, ANTI, CMSPR, CFP, MTP, ISD, AFL, LHCG, REG)	Each represents a synthetic player constructed to stress-test a specific schema feature. Names are mnemonic — e.g., HG = Hedger, DS = Distracted-Slow.

What's stable and what's open¶

Stable (won't change without new evidence)¶

The 70 primitives (14 captures + 22 extractions + 14 aggregations + 11 exposures + 9 measured outcomes)
The 4 causal layers + measured-outcomes structure
The 7 methodology principles
The 7 tagging conventions
The 9 promoted architectural findings

Open (will resolve as triggers fire)¶

5 parked questions — each has a specific condition that will trigger implementation. Most are gated on either substrate work (the cube going live in scenario generation) or product/eng decisions.
2 open questions that haven't been resolved:
OQ-within-session-stratification — should we measure learning within a single play session, not just across sessions? Low priority.

Outstanding decisions in plain language¶

Here's what needs to happen next, in priority order, with what's at stake:

1. ADR-074 follow-up format — your call (item 13)¶

Background: The schema work strengthened ADR-074's "no rebuild needed" claim with a more confident architectural property (the schema's design dimensions are mutually independent). This is supportable in light-paper positioning as "Pulse's measurement architecture is composable across domains" — stronger than the current defensive framing.

Three options: - A (cheap): Add a "Follow-up findings" subsection to ADR-074 referencing the alignment brief. - B (medium): Write a separate ADR (e.g., a future ADR — Measurement schema architectural independence) capturing this as a first-class architectural decision. Note: the originally-suggested ADR-076 slot is now occupied by the Multi-domain category taxonomy expansion ADR. - C (heavy): Revise ADR-074 to incorporate the strengthened framing directly.

Recommendation: A is cheapest. B is right if architectural independence becomes load-bearing for other work (light-paper, agent-builder pitch, multi-domain roadmap). C is overkill unless ADR-074 needs revision for other reasons.

Decision needed: Pick A, B, or C.

2. Run ADR-024 classify-driver backfill — eng work (item 15)¶

Background: When the team played their early games (before April 2026), the classify-driver pipeline that labels reasoning style and attention focus wasn't running. Result: 3 of 4 real teammate profiles (Amin, James, Zer8) have empty reasoning style and attention distributions today. Cici has rich data because she played enough after April. CoachJ has rich data because his profile has been continuously refreshed.

Why it matters: Without this backfill, when Hermes (or any agent) describes Amin/James/Zer8, it can't reference their reasoning style or attention pattern — those signals are null. The agent_context_block prose for these players is weaker than it could be.

What's involved: Run the classify-driver pipeline retroactively on stored rationale texts for affected accounts.

Decision needed: Approve eng work? Estimate cost?

3. OQ-1 + OQ-2 — product call¶

Background: Two questions about how to handle "None of the above" picks.

OQ-1: A player who often picks "None" (because the framing is wrong) gets zero sync-score points for those rounds. Their headline sync score collapses, even though their underlying profile is rich. The schema has a workaround (the agent prose can describe them via "frame-restructuring tendency" instead of the raw score) — but the headline still misrepresents them.
OQ-2: When a player picks "None," Pulse asks "which is closest?" — but for some players ("I'd actually do something completely different") this fabricates a preference signal. The schema records the forced-closest as if it were a real choice, contaminating downstream patterns.

Three closure options for each, ranging from light (cheap exposure-layer fix) to heavy (UX changes to capture intent properly). They're coupled: fixing OQ-2 the canonical way depends on first normalizing classify-driver for verbal style (a separate eng task).

Decision needed: Pick the closure shape for both.

4. 5 multi-swing closure paths — eng work¶

Five specific architectural improvements that the schema research surfaced, ready to ship when prioritized:

Add tab-focus tracking — closes the "distracted-slow vs deliberate-slow" misread in decision timing.
Add within-round option-tap tracking — closes the "solo players have no persuadability signal" gap.
Stratify aggregations by mode (solo vs multi) — surfaces calibration shifts that the current pooled view hides.
Surface sample-size in exposure — when N is small, prose should say "tentative" instead of asserting.
Surface "as of [date]" on state-sensitive outcomes — paste-based profiles for ChatGPT/Claude users should be clear about how stale the snapshot is.

Each is independent of the others (architectural independence finding). Can ship in any order.

Decision needed: Eng prioritization.

A specific fix to how reaction counts are aggregated. Currently a player who taps "gets me" but writes a contradicting note gets counted as agreement. The fix: classify the note text alongside the reaction. No new primitives, just an algorithm refinement. Already principle-7-aligned.

Decision needed: Eng prioritization.

6. E10 / E14 rename propagation — docs sweep (item 11)¶

The schema work renamed two signals from valuation-laden names to neutral ones: - "Rationale-choice alignment (authenticity)" → "Rationale-choice expression match" - "Self-aware aspiration gap" → "Ideal-actual reference frequency"

The reason: the old names carried interpretation ("inauthenticity," "aspiration gap" both sound negative when the same signal pattern could mean epistemic humility). Neutral names let downstream consumers commit to the right framing per context.

What's affected: Hermes prompts, agent context blocks, ADR-024 references — anywhere the old names appear.

Decision needed: Approve docs sweep.

7. Phase 3 cross-domain experiment — cube-doc work (item 9)¶

Tagging task for the cube doc, not the schema doc. The 10 scenarios designed for the cross-domain experiment need cube-C2 (expertise-requirement) tags before Phase 3 analysis. This was surfaced during the cube conversation, not schema research.

Decision needed: Cube-side prioritization.

8. Audit games_played vs games_analyzed counts — small data audit (item 16)¶

The real-profile decompositions surfaced that games_analyzed is consistently larger than games_played (Zer8 shows the largest gap: 11 vs 25). Probably means games_analyzed counts per-round events while games_played counts whole games — but unclear without checking the code.

Decision needed: Small audit; not blocking anything.

How to use this with collaborators¶

If you want to share the schema work with someone else (Amin, Cici, James, Tash, Cesar, etc.), here's the suggested order:

Start here (this reader's guide) — gives the plain-language picture and decodes the shorthand.
Then read measurement-schema.md (the canonical doc) — has the complete primitive enumeration. After reading the guide, the shorthand will make sense.
Skip measurement-schema-working.md unless they want the iteration history — it's deliberation context, not stable architecture.

If you want to pitch the architectural independence finding to someone:

"Pulse's measurement architecture is composable across domains. The schema's design dimensions — closure paths, measured outcomes, signals, conventions — are mutually independent. Adding new domains adds substrate; the measurement schema accommodates without rebalancing. This is stronger than 'no rebuild needed' — it's an active architectural property: composability. Every multi-domain expansion is bounded work."

If you want to explain the decomposition validation to someone:

"We ran 38 decompositions against the schema — 34 synthetic profiles spanning extreme cases (saturation, null-pattern, multi-pattern composites) plus 4 real teammate profiles. The schema correctly discriminates every profile shape we tested. No new primitives needed during decomposition. The schema validates against real production data."

If you want to explain what's still open to someone:

"Five concrete engineering improvements are ready to ship when prioritized. Each is independent of the others. The architectural independence finding means they can ship in any order without coordination overhead. Two product decisions (around 'None of the above' handling) are coupled but together cover most of the remaining UX-shape questions. Beyond that, the schema is stable."

What this guide is NOT¶

Not a replacement for the canonical doc — it leaves out specifics needed for actual implementation.
Not a tutorial on building Pulse — assumes you know what Pulse is.
Not a strategic plan — the schema is a measurement artifact; the strategy lives in ADR-074 and the light paper.
Not exhaustive — covers the 80% needed for decision-making; the canonical doc has the other 20%.