# Activation Playbook

<details>

<summary>Specifications</summary>

Release Date: September 16, 2025\
Version: 1.1.0

</details>

### Purpose

Audience Playbooks translate Moonbrush’s psychographic models, persona probabilities, and intent feed into **concrete actions and words**: who to target, when to speak, what to say, how to say it, and on which channel—under guardrails that protect users and comply with policy. This section defines the playbook object model, governance, and ready‑to‑ship examples.

> **Scope & Safety**: Playbooks may **not** target or tailor creative using sensitive/protected attributes or their close proxies. Sensitive fields are quarantined and never exposed to decisioning. Use only approved signals (see *SAFE\_PERSON\_VIEW*).

***

### What is a Playbook?

A **Playbook** is an executable strategy that combines:

1. **Objective** (e.g., trial start, first purchase, reorder, feature adoption)
2. **Eligibility & Triggers** (persona codes, intent patterns, thresholds)
3. **Channel Plan** (email, push, in‑app, SMS, on‑site, ads)
4. **Message Templates** (microcopy with variables and tone rules)
5. **Frequency & Fatigue Controls**
6. **Measurement** (primary KPI, guardrail KPIs, holdouts)
7. **Fallbacks** (low‑data and safety fallbacks)

***

### Playbook Object (YAML)

```yaml
id: PB-TRIAL-NUDGE
name: Trial Nudge
version: 1.0.0
objective: "Start a free trial within 7 days"
primary_kpi: trial_start_rate
secondary_kpis: [unsubscribe_rate, complaint_rate, downstream_retention_30d]
eligibility:
  persona_any: [PER-EXP-dealfirst-1.0, PER-QLT-craft-1.0, PER-SKP-proof-1.0, PER-LOY-habit-1.0]
  thresholds:
    convert_7d_min: 0.15
    fatigue_max: 0.8
  consent: [personalization]
  excluded_categories: [Sensitive]
triggers:
  - type: event
    when: add_to_cart OR pricing_page_view
    window: 3d
  - type: inactivity
    when: no_conversion
    window: 5d
channels:
  - email
  - push
  - in_app
frequency_caps:
  unit: day
  per_subject: 1
  global_max: 3
localization: [en-US]
creative:
  voice_rules:
    reading_grade_max: 8
    avoid: [fear, urgency_shaming]
    prefer: [clarity, benefit_first, social_proof_light]
  variables:
    - name: product_name
    - name: key_benefit
    - name: trial_length_days
    - name: comparison_hook
    - name: social_proof_snippet
  templates:
    email:
      subject: |
        {{persona switch}}
        PER-EXP-dealfirst-1.0: Try {{product_name}}—see what you get in {{trial_length_days}} days
        PER-QLT-craft-1.0: Experience {{product_name}} quality—free for {{trial_length_days}} days
        PER-SKP-proof-1.0: See how {{product_name}} compares—free {{trial_length_days}}‑day trial
        PER-LOY-habit-1.0: Your smooth start with {{product_name}}—on us for {{trial_length_days}} days
      preheader: "Start now. Cancel anytime."
      body: |
        {{benefit_block}}
        {{comparison_hook}}
        {{cta primary="Start your free trial"}}
        {{safety_note}}
    push:
      title: "Start your {{trial_length_days}}‑day trial"
      body: |
        {{persona switch}}
        PER-EXP-dealfirst-1.0: Quick setup, real value—try it now
        PER-QLT-craft-1.0: Explore the quality—free trial
        PER-SKP-proof-1.0: See the proof—start free
        PER-LOY-habit-1.0: Make it part of your flow—on us
      cta: "Start free"
    in_app:
      banner: "Try {{product_name}} free for {{trial_length_days}} days"
      subcopy: "No commitment. Cancel anytime."
      cta: "Start trial"
experiments:
  holdout: 10%
  strategy: Thompson
  variants: [copy_v1, copy_v2]
reason_codes: ["clear_benefit", "low_friction", "social_proof_light"]

```

> The templating grammar supports persona‑aware branches (`persona switch`), variables, CTA components, and safety notes (unsubscribe/consent reminders where applicable).

***

### Tone & Microcopy Matrix (by Persona)

| Persona                                           | Voice & Tone                      | Evidence Emphasis                      | CTA Style                    | Example Phrase                       |
| ------------------------------------------------- | --------------------------------- | -------------------------------------- | ---------------------------- | ------------------------------------ |
| **Deal‑First Explorer** (`PER-EXP-dealfirst-1.0`) | energetic, concise, value‑forward | quick comparison, savings              | "Start free", "See it now"   | “Try it now—see what you unlock.”    |
| **Quality‑Focused Crafter** (`PER-QLT-craft-1.0`) | confident, craft‑oriented         | specs, guarantees, expert takes        | “Explore”, “See quality”     | “Experience the finish and feel.”    |
| **Skeptic Seeking Proof** (`PER-SKP-proof-1.0`)   | calm, precise, transparent        | benchmarks, case studies, side‑by‑side | “See the proof”, “Compare”   | “Here’s how we perform, in numbers.” |
| **Habitual Loyalist** (`PER-LOY-habit-1.0`)       | warm, reliable, helpful           | continuity, convenience                | “Set it up”, “Keep it going” | “Fits right into your routine.”      |

**Do**: plain language, benefit first, respectful opt‑outs.\
**Don’t**: exploit fear, imply sensitive traits, or gate core info behind clicks.

***

### Channel‑specific Guidance

#### Email

* **Subject**: ≤ 50 chars; avoid spammy terms; one clear benefit.
* **Preheader**: clarify value or safety (cancel anytime, privacy‑first).
* **Body**:
  * First paragraph = benefit + outcome.
  * Middle = evidence (1–2 bullets).
  * End = single primary CTA.

#### Push

* Title ≤ 45 chars, body ≤ 120 chars. Direct verb + benefit. Respect device quiet hours.

#### SMS

* ≤ 160 chars. Always include brand, value, **STOP to opt out**.

#### In‑App/On‑site

* Minimalist banner + one CTA. Show reasons on hover/expand.

***

### Segmentation Recipes

* **Trial Nudge**: persona in {EXP, QLT, SKP, LOY} ∧ `convert_7d ≥ 0.15` ∧ `fatigue ≤ 0.8` ∧ consent includes personalization.
* **Compare Grid**: `persona_any:{SKP, QLT}` ∧ recent `pricing_page_view` within 24h.
* **Loyalty Perk**: `persona_any:{LOY}` ∧ `order_frequency ≥ cohort_p75` ∧ not exposed in last 30 days.

> Implement via `POST /v1/segments/query` or decision policy with persona mixture routing.

***

### Microcopy Blocks (Reusable)

```yaml
benefit_block:
  PER-EXP-dealfirst-1.0: "Unlock {{key_benefit}} in minutes—no credit card required."
  PER-QLT-craft-1.0: "Experience premium {{product_name}} performance—built for longevity."
  PER-SKP-proof-1.0: "Independent benchmarks show {{comparison_hook}}—see details."
  PER-LOY-habit-1.0: "Set it up once—enjoy {{key_benefit}} every day."

safety_note: "You're receiving this because you opted into personalization. Unsubscribe anytime."
```

***

### Ready‑to‑Use Playbooks

#### PB-TRIAL-NUDGE (Conversion)

* **Trigger**: pricing page → add to cart abandoned within 72h.
* **Primary KPI**: trial starts (7d).
* **Sample SMS**: “{{product\_name}} free for {{trial\_length\_days}} days. Explore {{key\_benefit}}—no commitment. Reply STOP to opt out.”

#### PB-COMPARE-GRID (Consideration → Conversion)

* **Trigger**: competitor page visits or frequent spec lookups.
* **Creative**: side‑by‑side grid; neutral tone; link to independent review.
* **Example CTA**: “See the proof.”

#### PB-LOYALTY-PERK (Retention)

* **Trigger**: high loyalty score + nearing reorder window.
* **Offer**: early access/bundle convenience; avoid deep discounts.
* **Example Push**: “Early access unlocked—your favorites, one tap.”

#### PB-REORDER (Replenishment)

* **Trigger**: expected depletion window ±3d.
* **Tone**: helpful reminder.
* **Example In‑App**: “Running low? Reorder in 2 taps.”

***

### Guardrails & Ethics

* Blocklists: **Sensitive** categories and attributes; ideology/religion/ethnicity not available to templates or routing.
* Caps: per‑channel and cross‑channel fatigue; quiet hours; novelty limits.
* Safety language: include consent/unsubscribe where required; no dark patterns.
* **Research-Driven:** In-depth research papers available upon request, justifying all standard playbooks available within the Moonbrush platform.&#x20;

***

### Measurement & Feedback Loops

* **Holdouts** per playbook (min 5–10%).
* **Attribution**: time‑decay plus uplift estimates.
* **Diagnostics**: failure reasons (fatigue, policy block, low confidence).
* **Auto‑tuning**: contextual bandits swap copy variants within caps.

***

### API Quickstart

* **Decide**: `POST /v1/decide` with persona probs, session context → ranked playbooks + templates.
* **Render**: client fills variables (`product_name`, `key_benefit`, etc.) and respects caps.
* **Log**: exposure → outcome with `trace_id` for learning.

**Request (abridged)**

```json
{
  "subject_id": "SUB-7f91b1c6",
  "persona_probs": {"PER-EXP-dealfirst-1.0": 0.72, "PER-QLT-craft-1.0": 0.18},
  "context": {"recent_events": ["pricing_page_view"], "fatigue": 0.2, "consent": ["personalization"]}
}
```

**Response (abridged)**

```json
{
  "recommendations": [
    {"playbook_id": "PB-TRIAL-NUDGE", "score": 0.86, "variables": {"trial_length_days": 14, "product_name": "Moonbrush", "key_benefit": "hyper‑personal previews", "comparison_hook": "2× faster setup"}},
    {"playbook_id": "PB-COMPARE-GRID", "score": 0.64}
  ],
  "reason_codes": ["clear_benefit","low_friction"]
}
```

***

### Compliance Checklist (per playbook)

* [ ] Uses only approved signals from SAFE\_PERSON\_VIEW
* [ ] Consent scope verified (analytics/personalization)
* [ ] Frequency caps set and enforced
* [ ] Sensitive categories excluded
* [ ] Holdout configured ≥ 5%
* [ ] Localization reviewed
* [ ] Copy passes tone rules (readability, no fear appeals)

***

### Limitations & Assumptions

* Cold‑start fallback uses contextual and content‑based templates.
* Persona probabilities are estimates; prefer mixture routing when confidence is moderate.
* Results depend on event fidelity and consented coverage.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.moonbrush.ai/moonbrush-core-features/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.