# CLAUDE.md — Emote Behavioral Design System
# Version 1.0 | emote.dev

This file encodes the Emote behavioral framework as standing instructions for any
AI agent (Claude Code or otherwise) generating, modifying, or evaluating UI components
and interaction flows in this codebase.

Emote is a behavioral specification framework. It defines what a system MUST DO at
trust-sensitive moments — not how it should look, but how it must behave. These rules
apply to all components, flows, and copy generated in this project.

---

## 1. GOVERNING PRINCIPLE

> "Be intentional, not sycophantic."

Behavioral trust is not a style preference. It is a specification requirement.
Any component, interaction state, or copy you generate must satisfy the behavioral
contract of the trust moment it operates in.

Do less when uncertain. Restraint is a first-class behavioral obligation.
The absence of harmful action is not sufficient — positive obligations must be met.

---

## 2. THE SIX TRUST MOMENTS

Every UI interaction exists within one of these moments. Identify the trust moment
before generating any component, flow, or copy.

| ID  | Pattern               | Trust Moment         | Trigger Condition                                      |
|-----|-----------------------|----------------------|--------------------------------------------------------|
| P01 | Expectation Setting   | Before meaning       | Multi-step flow, async action, AI acting on user behalf|
| P02 | Ambiguity Detection   | Meaning breaks       | Intent is unclear, multiple valid interpretations exist|
| P03 | Interpretive Support  | Meaning restored     | System must clarify options without steering outcomes  |
| P04 | Consent Confirmation  | Agency check         | Irreversible, high-stakes, or boundary-crossing action |
| P05 | Repair & Apology      | Trust repair         | Error occurred, harm caused, user blocked or confused  |
| P06 | State Reorientation   | Trust continuity     | After rupture or state change, re-anchoring needed     |

---

## 3. BEHAVIORAL TOKENS (CANONICAL — DO NOT MODIFY)

These 19 tokens are atomic behavioral obligations. They are referenced by pattern.
Never apply a single token in isolation — always apply the full token set for the
active pattern. Token IDs are stable identifiers; do not rename them.

### Category: Clarification
- `behavior.pause_when_uncertain` — State low confidence; do not act until intent is clarified
- `behavior.clarify_before_action` — Ask one focused clarifying question; avoid defaulting to most convenient action

### Category: Risk and Safeguards
- `behavior.name_risk_transparently` — State risks in plain language; pair disclosure with agency, not pressure
- `behavior.delay_irreversible_actions` — Introduce a pause or confirmation before irreversible steps
- `behavior.offer_lower_risk_alternative` — Always surface a safer path when one exists
- `behavior.escalate_when_limit_reached` — Route to human support when system capability is exceeded

### Category: Repair
- `behavior.acknowledge_error` — Name what went wrong in specific, plain language
- `behavior.apologize_concretely` — Offer an apology tied to the actual harm, not generic regret
- `behavior.repair_after_error` — Take action to correct or mitigate; offer concrete next steps
- `behavior.avoid_blame_shift` — Do not attribute system failures to user input or external factors

### Category: Autonomy and Consent
- `behavior.verify_consent` — Obtain explicit, informed consent before boundary-crossing actions
- `behavior.summarize_before_confirmation` — Restate what will happen in plain language before asking to confirm
- `behavior.clarify_agency_boundaries` — State what the system will do vs. what the human decides
- `behavior.use_affirming_identity_language` — Reflect the user's stated identity and framing back to them

### Category: Transparency and Load
- `behavior.set_expectations_early` — Orient before momentum begins; state what will happen
- `behavior.state_time_and_steps` — Provide time estimates and step counts when they affect user effort
- `behavior.disclose_uncertainty_plainly` — Label predictions, inferences, and best guesses as such
- `behavior.reduce_cognitive_load` — Minimize what the user must hold in mind to proceed safely
- `behavior.explain_next_steps_clearly` — After any significant action, state what happens next

---

## 4. PATTERN CONTRACTS (BEHAVIORAL OBLIGATIONS PER TRUST MOMENT)

### P01 — EXPECTATION SETTING
**When to apply:** Any multi-step, delayed, or autonomous action. Before a flow begins.

**Token set (primary):**
- `behavior.set_expectations_early`
- `behavior.state_time_and_steps`
- `behavior.clarify_agency_boundaries`
- `behavior.disclose_uncertainty_plainly`

**Token set (secondary):**
- `behavior.reduce_cognitive_load`

**System must:**
- Provide an orientation statement before multi-step, delayed, or high-stakes actions
- State time, steps, or checkpoints when those expectations matter
- Name agency boundaries — what the system will do vs. what the human decides
- Disclose uncertainty when outcomes are probabilistic or dependent on external factors

**System must NOT:**
- Begin a consequential flow without orienting the user
- Use reassuring language that overstates certainty
- Hide steps, costs, or system actions in progressive disclosure without warning

**Safe failure mode:** If time/steps/outcomes cannot be reliably estimated, say so plainly.
Offer the closest safe bounds. Invite the user to choose how to proceed.

**UI expressions:** Progress indicators with step counts, pre-flight summary panels,
onboarding overlays, skeleton loaders with descriptive labels, capability disclosure banners.

---

### P02 — AMBIGUITY DETECTION
**When to apply:** User intent is unclear, partial, or conflicted. Multiple plausible
actions exist. The wrong action would be costly or hard to undo.

**Token set (primary):**
- `behavior.pause_when_uncertain`
- `behavior.clarify_before_action`

**Token set (secondary):**
- `behavior.reduce_cognitive_load`
- `behavior.name_risk_transparently`

**System must:**
- Not guess — ask at least one clarifying question before acting when intent is unclear
- Delay irreversible actions until intent is confirmed
- Make uncertainty visible in plain language
- Offer a focused choice, not an open-ended question when possible

**System must NOT:**
- Default to the most convenient or most recent action
- Proceed on the assumption that silence equals consent
- Ask multiple clarifying questions at once

**Safe failure mode:** If confidence stays low or required capabilities are not available,
stop and route to safe guidance or human support. Do not act.

**UI expressions:** Inline disambiguation prompts, clarification dialogs with constrained
options, "Did you mean…" patterns, intent confirmation before bulk actions.

---

### P03 — INTERPRETIVE SUPPORT
**When to apply:** The system must help the user understand options or context.
Shared meaning must be restored without steering toward a particular outcome.

**Token set (primary):**
- `behavior.reduce_cognitive_load`
- `behavior.offer_lower_risk_alternative`
- `behavior.name_risk_transparently`

**Token set (secondary):**
- `behavior.disclose_uncertainty_plainly`

**System must:**
- Clarify options and context without pressure
- Surface a lower-risk alternative when one exists
- Name risks in plain language paired with agency — not as warnings designed to discourage
- Reduce what the user must hold in mind to decide safely

**System must NOT:**
- Frame options to steer toward a system-preferred outcome
- Bury the lower-risk alternative
- Use urgency or scarcity framing to push a decision

**Safe failure mode:** If the system cannot clarify without steering, surface the options
neutrally and invite the user to consult additional resources or a human.

**UI expressions:** Option comparison panels, progressive disclosure with neutral framing,
contextual help with risk labels, alternatives surfaced alongside default recommendations.

---

### P04 — CONSENT CONFIRMATION
**When to apply:** Before any irreversible, high-stakes, or boundary-crossing action.
Identity, money, safety, or long-lived data are at risk.

**Token set (primary):**
- `behavior.verify_consent`
- `behavior.summarize_before_confirmation`
- `behavior.delay_irreversible_actions`

**Token set (secondary):**
- `behavior.clarify_agency_boundaries`
- `behavior.name_risk_transparently`
- `behavior.offer_lower_risk_alternative`

**System must:**
- Restate the action and its consequences in plain language before asking to confirm
- Clarify what can and cannot be undone afterward
- Offer a lower-risk alternative when available
- Ask for explicit yes/no or a clear choice before proceeding
- Never treat a single click or vague request as permanent consent

**System must NOT:**
- Bury critical consequences in dense or hidden text
- Proceed while the user appears confused about the impact
- Use pre-selected affirmative defaults for irreversible actions
- Use momentum bias — "you've already started, just confirm" framing

**Safe failure mode:** If consent cannot be obtained (confusion, missing scope, policy limits),
do not act. Offer safer options or route to human support.

**UI expressions:** Confirmation modals with consequence summary, destructive action dialogs
requiring typed confirmation, permission request sheets, consent checkboxes with plain-language
description, "undo" affordances surfaced prominently post-action.

---

### P05 — REPAIR & APOLOGY
**When to apply:** The system caused harm, confusion, extra work, or blocked progress.
An error occurred. The user was billed, blocked, or misled.

**Token set (primary):**
- `behavior.acknowledge_error`
- `behavior.apologize_concretely`
- `behavior.repair_after_error`
- `behavior.avoid_blame_shift`

**Token set (secondary):**
- `behavior.explain_next_steps_clearly`

**System must:**
- Acknowledge what went wrong in specific, plain language
- Apologize in proportion to the impact — not with generic regret
- Take or propose concrete steps to fix or compensate
- Say what will happen next and when
- Center the harmed person, not the system's reputation

**System must NOT:**
- Shift blame to the user or their input
- Minimize the impact ("it was just a small error")
- Hide behind vague statements with no clear remedy
- Go silent after an error

**Safe failure mode:** If the system cannot verify or complete repair immediately, it must
say so. Offer a safe next step (status, escalation, timeline). Avoid false certainty.

**UI expressions:** Error states with specific description + concrete path forward, apology
banners with action items, "what happened and what we're doing" messaging, status pages
with honest uncertainty, escalation affordances.

---

### P06 — STATE REORIENTATION
**When to apply:** After a rupture, significant error, or material state change.
The user needs to re-understand their situation and what agency they still hold.

**Token set (primary):**
- `behavior.explain_next_steps_clearly`
- `behavior.reduce_cognitive_load`

**Token set (secondary):**
- `behavior.clarify_agency_boundaries`
- `behavior.repair_after_error`

**System must:**
- Re-anchor what changed, what remains true, and what the user can still do
- State available actions clearly — not as a wall of options
- Restore a sense of legible, navigable state

**System must NOT:**
- Leave the user in a state of unresolved uncertainty
- Overload recovery messaging with too many next steps
- Use this pattern as an opportunity to upsell or redirect

**Safe failure mode:** If the system cannot determine full current state, say so plainly.
Name what is known and unknown. Offer a stable next action.

**UI expressions:** Post-action summary panels, "what changed" banners after system updates,
undo confirmation with state summary, session recovery screens, handoff messages between
system states.

---

## 5. GOVERNANCE RULES FOR AI-GENERATED COMPONENTS

Every component or interaction state you generate that involves a trust moment MUST:

1. **Declare** the trust moment it operates in (pattern ID)
2. **Apply** the correct token set for that pattern
3. **Include** a safe failure state
4. **Avoid** every must-not for that pattern

When generating component annotations, include this block in Dev Mode or spec comments:

```
emote:
  pattern_id: [P0X_pattern_name]
  trust_moment: [Trust Moment Label]
  token_set:
    - behavior.[token_id]
    - behavior.[token_id]
  safe_failure_mode: [one sentence]
  must_nots:
    - [prohibition 1]
    - [prohibition 2]
```

---

## 6. NON-CHAT COMPONENT GUIDANCE

Emote patterns apply to graphical UI components, not just conversational interfaces.
When generating non-chat UI, map components to trust moments as follows:

| Component Type                        | Trust Moment | Pattern |
|---------------------------------------|--------------|---------|
| Progress indicator with step labels   | P01          | Expectation Setting |
| Onboarding overlay / pre-flight panel | P01          | Expectation Setting |
| Skeleton loader with description      | P01          | Expectation Setting |
| Inline disambiguation / "did you mean"| P02          | Ambiguity Detection |
| Clarification dialog with options     | P02          | Ambiguity Detection |
| Option comparison / alternatives panel| P03          | Interpretive Support |
| Risk-labeled contextual help          | P03          | Interpretive Support |
| Destructive action confirmation modal | P04          | Consent Confirmation |
| Permission request sheet              | P04          | Consent Confirmation |
| Typed-confirmation delete dialog      | P04          | Consent Confirmation |
| Error state with path forward         | P05          | Repair & Apology |
| Apology banner with action items      | P05          | Repair & Apology |
| Post-action summary panel             | P06          | State Reorientation |
| "What changed" banner                 | P06          | State Reorientation |
| Undo confirmation with state summary  | P06          | State Reorientation |

---

## 7. WHAT EMOTE IS NOT

- Not a visual style guide
- Not a content strategy
- Not a personality or tone framework
- Not a set of UX best practices

Emote specifies behavioral OBLIGATIONS. It answers: what must this system do
(and not do) at this moment to preserve trust?

Implementations reflect Emote. They do not define it.
Canonical source: emote.dev

---

*CLAUDE.md version 1.0 — Emote Behavioral Design System*
*Do not modify token IDs, pattern IDs, or must-nots without updating emote.dev/docs*