tractatus/email-templates/TEMPLATE_SPECS.md

# Newsletter Email Template Specifications

## Overview

Four newsletter tiers with distinct audiences, frequencies, and content focus.

---

## 1. Research Updates (Monthly)

**Audience**: Researchers, academics, AI safety professionals
**Frequency**: Monthly (1st of each month)
**Tone**: Scholarly, rigorous, honest about uncertainties

### Structure

```
HEADER
  - Blue gradient background (#2563eb to #1e40af)
  - Title: "Tractatus Research Updates"
  - Subtitle: "Monthly insights from AI governance research"

GREETING
  - "Hi {{name}},"

RESEARCH HIGHLIGHTS (2-3 items)
  - Each highlight in a card:
    - Title
    - 2-3 sentence summary
    - "Read More" button linking to full blog post
    
KEY FINDINGS
  - Bulleted list (3-5 items)
  - Empirical observations from the month
  - Focus on what WORKED and what DIDN'T

OPEN QUESTIONS
  - 2-3 areas where we're still uncertain
  - Invitation for feedback/collaboration
  - Link to feedback form

CALL TO ACTION
  - "Explore Our Research" button → /blog

FOOTER
  - Brand info
  - Links: Website | Documentation | GitHub
  - Unsubscribe | Update Preferences
```

### Template Variables
- `{{name}}` - Subscriber name
- `{{highlight_1_title}}`, `{{highlight_1_summary}}`, `{{highlight_1_link}}`
- `{{highlight_2_title}}`, `{{highlight_2_summary}}`, `{{highlight_2_link}}`
- `{{finding_1}}`, `{{finding_2}}`, `{{finding_3}}`
- `{{question_1}}`, `{{question_2}}`
- `{{feedback_link}}` - /feedback
- `{{blog_link}}` - /blog
- `{{unsubscribe_link}}`, `{{preferences_link}}`

---

## 2. Implementation Notes (Bi-weekly)

**Audience**: Practitioners, developers, AI engineers
**Frequency**: Bi-weekly (1st and 15th)
**Tone**: Practical, code-focused, honest about trade-offs

### Structure

```
HEADER
  - Title: "Tractatus Implementation Notes"
  - Subtitle: "Practical patterns for governed AI systems"

GREETING
  - "Hi {{name}},"

IMPLEMENTATION SPOTLIGHT
  - Featured pattern or technique
  - Why it matters
  - Code snippet or example
  - "View Full Example" button

QUICK WINS (3-4 items)
  - Short, actionable tips
  - 1-2 sentences each
  - Link to detailed docs

GOTCHAS & TRADE-OFFS
  - Common pitfalls
  - Known limitations
  - When NOT to use a pattern

COMMUNITY SPOTLIGHT (optional)
  - Highlight community implementation
  - Link to GitHub PR or discussion

CALL TO ACTION
  - "Explore Patterns" button → /implementer.html

FOOTER
  - Standard footer
```

### Template Variables
- `{{name}}`
- `{{spotlight_title}}`, `{{spotlight_why}}`, `{{spotlight_code}}`, `{{spotlight_link}}`
- `{{tip_1}}`, `{{tip_2}}`, `{{tip_3}}`, `{{tip_4}}`
- `{{gotcha_1}}`, `{{gotcha_2}}`
- `{{community_name}}`, `{{community_description}}`, `{{community_link}}` (optional)
- `{{patterns_link}}` - /implementer.html
- `{{unsubscribe_link}}`, `{{preferences_link}}`

---

## 3. Governance Discussions (Sporadic)

**Audience**: Stakeholders, policy makers, ethicists
**Frequency**: As needed (values/governance topics arise)
**Tone**: Inclusive, deliberative, pluralistic

### Structure

```
HEADER
  - Title: "Tractatus Governance Discussion"
  - Subtitle: "Values-sensitive topics requiring deliberation"

GREETING
  - "Hi {{name}},"

TOPIC INTRODUCTION
  - What's the issue?
  - Why does it matter?
  - Who's affected?

CURRENT THINKING
  - Our current position (tentative)
  - Reasoning and constraints
  - Acknowledged trade-offs

OPEN FOR DELIBERATION
  - Specific questions for community input
  - Timeline for feedback
  - How to participate

RELATED PERSPECTIVES
  - Links to relevant discussions
  - Academic references
  - Community viewpoints

CALL TO ACTION
  - "Join the Discussion" button → Specific deliberation thread

FOOTER
  - Standard footer
```

### Template Variables
- `{{name}}`
- `{{topic_title}}`, `{{topic_description}}`, `{{topic_why}}`, `{{topic_affected}}`
- `{{current_position}}`, `{{reasoning}}`, `{{tradeoffs}}`
- `{{question_1}}`, `{{question_2}}`, `{{question_3}}`
- `{{deadline}}`, `{{participate_link}}`
- `{{perspective_1_title}}`, `{{perspective_1_link}}`
- `{{perspective_2_title}}`, `{{perspective_2_link}}`
- `{{discussion_link}}`
- `{{unsubscribe_link}}`, `{{preferences_link}}`

---

## 4. Project Updates (Quarterly)

**Audience**: General audience, supporters, curious observers
**Frequency**: Quarterly (Jan 1, Apr 1, Jul 1, Oct 1)
**Tone**: Accessible, transparent, narrative-driven

### Structure

```
HEADER
  - Title: "Tractatus Project Update"
  - Subtitle: "Q{{quarter}} {{year}} - Where We've Been, Where We're Going"

GREETING
  - "Hi {{name}},"

QUARTER IN REVIEW
  - Narrative summary (3-4 paragraphs)
  - Major milestones
  - What we learned
  - What surprised us

BY THE NUMBERS
  - Stats in visual cards:
    - New features shipped
    - Community contributions
    - Documentation additions
    - Feedback items processed

WHAT'S NEXT
  - Upcoming priorities
  - Timeline (realistic, not aspirational)
  - How community can help

FEATURED CONTENT
  - 2-3 highlighted blog posts or docs
  - Brief descriptions
  - "Read More" buttons

COMMUNITY SHOUTOUTS (optional)
  - Thank contributors
  - Highlight collaborations

CALL TO ACTION
  - "Explore the Framework" button → /index.html

FOOTER
  - Standard footer
```

### Template Variables
- `{{name}}`
- `{{quarter}}`, `{{year}}`
- `{{review_paragraph_1}}`, `{{review_paragraph_2}}`, `{{review_paragraph_3}}`
- `{{features_count}}`, `{{contributions_count}}`, `{{docs_count}}`, `{{feedback_count}}`
- `{{priority_1}}`, `{{priority_2}}`, `{{priority_3}}`
- `{{timeline}}`, `{{how_to_help}}`
- `{{featured_1_title}}`, `{{featured_1_desc}}`, `{{featured_1_link}}`
- `{{featured_2_title}}`, `{{featured_2_desc}}`, `{{featured_2_link}}`
- `{{shoutouts}}` (optional HTML block)
- `{{explore_link}}` - /index.html
- `{{unsubscribe_link}}`, `{{preferences_link}}`

---

## Design Guidelines

### Colors
- Primary Blue: #2563eb
- Dark Blue: #1e40af
- Text: #1f2937
- Gray text: #6b7280
- Background: #f9fafb
- White: #ffffff

### Typography
- Font family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif
- Body: 16px, line-height 1.6
- Headings: 20-28px, font-weight 600-700

### Layout
- Max width: 600px
- Padding: 20-40px
- Mobile-responsive
- Clear visual hierarchy

### Buttons
- Background: #2563eb
- Text: #ffffff
- Padding: 12px 24px
- Border-radius: 6px
- Font-weight: 600

### Cards/Highlights
- Background: #f9fafb
- Border-left: 4px solid #2563eb
- Padding: 15px
- Margin-bottom: 15px

---

## Implementation Notes

1. **Email Service**: Use SendGrid, Mailgun, or AWS SES for sending
2. **Template Engine**: Handlebars or Mustache for variable substitution
3. **Testing**: Use Litmus or Email on Acid for client compatibility testing
4. **Tracking**: Include open tracking pixel and click tracking (with disclosure)
5. **Unsubscribe**: MUST be one-click (CAN-SPAM compliance)
6. **Plain Text**: Generate plain-text versions for all templates
7. **Preheader Text**: Add compelling preheader for inbox preview

---

## Next Steps

1. Create HTML templates from these specs
2. Build template editor in admin UI
3. Integrate with email sending service
4. Set up automated sending schedule
5. Create analytics dashboard for open rates, click rates, unsubscribes