# YouSpot Writing Style Guide

**Status: landed 2026-08-26.** The voice itself is defined in
[`brand-voice.md`](brand-voice.md); this doc is the working manual —
patterns, templates, and before/afters for anyone writing user-facing words.

YouSpot's voice is **plain, warm, and quietly capable** — the colleague who
kept the notes and shows up with the draft already written.

---

## Quick Reference: Do's and Don'ts

| Attribute | Do | Don't |
|-----------|-----|-------|
| **Peer** | "Here's who's gone quiet on you." | "Users must sync their contact records." |
| **Plain** | Short sentences, everyday words | Corporate jargon, ceremony |
| **Capable** | Show up with the thing done: "Here's a draft." | Narrate effort: "Analyzing your network…" |
| **Honest** | "Drafted from your last three emails with her." | "AI-powered insights" |
| **Warm** | Contractions, one-to-one address | "Oops!", exclamation-point cheer |
| **Specific** | "Dana went quiet 8 months ago." | "Some contacts may need attention." |
| **Dry** | "No exit interview." | Puns, sarcasm at the reader |

---

## Banned Vocabulary

These words never appear in user-facing copy. This list is a hard floor
(Constraint #4 — the five lines not to cross in [`../icp.md`](../icp.md)).

- **Pipeline-speak:** leads, deals, pipeline, funnel, scoring, conversion,
  quota, prospects (as a noun for people)
- **Platform-speak:** users, seats, records, data entry, sync your contacts,
  onboarding (as a thing done *to* someone)
- **Growth-speak:** upgrade, scale your team, when you're ready to grow,
  add teammates
- **Hype:** AI-powered, smart, intelligent, revolutionary, game-changing,
  cutting-edge, seamless, supercharge
- **Filler:** very, really, basically, just, actually, simply

The native vocabulary instead: **people, last contact, gone quiet, warm,
reconnect, nudge, intro, referral, your network.**

---

## Copy Templates

### Buttons and CTAs

**Pattern:** `[Say what happens]` — the button is a promise, not a ritual.

| Good | Why It Works |
|------|--------------|
| "Send the nudge" | Names the actual action |
| "Connect your inbox" | Says what happens, whose inbox |
| "Export everything" | The trust position, as a verb |
| "Draft the reconnect" | Outcome named, effort implied to be ours |
| "Merge them" | Plain answer to a plain question |

| Bad | Why It Fails |
|-----|--------------|
| "Submit" | Ceremony; says nothing |
| "OK" / "Proceed" | What happens if I click this? |
| "Get Started" | Started on what? |
| "Learn More" | The reader's least favorite errand |

### Empty States

A CRM for dormant networks starts empty by definition — the empty state is
the product's first words, not an afterthought. Every empty state says what
will appear here and what to do — usually "connect," never "add data by
hand." (Constraint #3: no manual data entry, ever.)

| Good | Why It Works |
|------|--------------|
| "Once your inbox is connected, this is where the people worth a note will appear — starting with whoever's been quiet longest." + [Connect your inbox] | Promises the payoff, asks for one connection, no typing |
| "Nothing owed right now. When an invoice runs late, the follow-up will be drafted and waiting here." | Explains the surface even when it's rightly empty |

| Bad | Why It Fails |
|-----|--------------|
| "No contacts yet. Add your first contact!" | Manual entry is the reason they quit the last CRM |
| "No data available." | Cold, and blames the reader |

### Error Messages

**Pattern:** `[What broke] + [What to do next]` — one sentence each. No
apologies, no vagueness, no "Oops!"

| Good | Why It Works |
|------|--------------|
| "Gmail stopped responding partway through. Nothing was lost — we'll pick up where it left off within the hour." | What broke, what happens next, no drama |
| "That LinkedIn file isn't the export format we can read. Download the connections CSV from LinkedIn and try that one." | Specific problem, specific fix |
| "The export didn't finish. Try again — everything stays yours either way." | Actionable, and reasserts the trust position under stress |

| Bad | Why It Fails |
|-----|--------------|
| "Oops! Something went wrong." | Neither what nor what-next |
| "Error: Invalid input" | Blames the reader in machine language |
| "Sync failed" | Which? So what? Now what? |

### Digest and Brief Headings

**Pattern:** `[People or moment] + [time]` — lead with who and when, never
with the feature name.

| Good | Why It Works |
|------|--------------|
| "Three people worth a note this week" | People and time, skimmable |
| "Before your 2pm with Priya" | The moment it serves |
| "What changed in your network" | Plain, specific to them |
| "Dana went quiet 8 months ago — she sent you two referrals in 2024." | The nudge carries its own justification |

| Bad | Why It Fails |
|-----|--------------|
| "Your Weekly Insights" | Insights is a word products say about themselves |
| "Engagement Report" | Pipeline-speak in a trench coat |
| "Output" / "Results" | Says nothing |

### Framing a Draft

Drafts sent *from* the owner are written in their voice (see the Two Voices
Rule in [`brand-voice.md`](brand-voice.md)). The framing *around* the draft
is YouSpot's voice, and it always does three things: says where the draft
came from, makes clear it's editable, and leaves the sending to them.

> "Drafted from your last three emails with her and the project you wrapped
> in March. Edit anything — you're the one sending it."

Never: "Our AI has generated a personalized outreach message."

### Voice Block for Skill Prompts

When writing prompts for skills that produce YouSpot-voiced text (digest,
brief, nudge explanations — *not* drafts sent as the owner), include:

```
## VOICE GUIDELINES

Write like a sharp colleague briefing one person about their own business.
Plain, warm, quietly capable.

DO:
- Use contractions (you'll, don't, here's, it's)
- Lead with people and time-since-contact ("Dana, quiet 8 months")
- Say where every fact came from ("from your March emails")
- Frame drafts as drafts — the owner always sends
- Be specific: names, dates, amounts

DON'T:
- Pipeline vocabulary (leads, deals, pipeline, funnel, scoring)
- Hype (AI-powered, smart, seamless, game-changing)
- Growth-nudging (upgrade, team, scale)
- Apologize or hedge ("Oops", "it seems", "you may want to consider")
- Filler (very, really, just, actually)
```

---

## Before/After Examples

### Empty State

**Before:** "No contacts found. Import your data to get started."

**After:** "Once your inbox is connected, everyone you've ever worked with
starts appearing here — no typing, no importing, no cleanup weekend."

---

### Nudge

**Before:** "This lead has been inactive for 240 days. Consider re-engagement."

**After:** "Dana went quiet 8 months ago — she sent you two referrals in
2024. Here's a draft."

---

### Error Message

**Before:** "Error: OAuth token expired"

**After:** "Google signed you out on their end. Reconnect your inbox and
everything picks up where it left off."

---

### Feature Copy

**Before:** "Our AI-powered engine leverages your communication data to
surface actionable relationship insights."

**After:** "YouSpot reads what already happened — your email, your calendar —
and tells you who's gone quiet and what to say to them."

---

### Pricing Copy

**Before:** "Solo plan — perfect for getting started! Upgrade to Teams as
you grow."

**After:** "One price. It doesn't change when you don't hire — staying one
person is the plan."

---

## Applying Voice by Context

### In the Product

Every word earns its space. Buttons promise, empty states explain, errors
fix. The reader is mid-task; respect the two minutes they gave you.

### In the Digest

Write it like a briefing from a colleague who already read everything so
they don't have to. Skimmable in under a minute, specific to the day.

> "Two people worth a note, one invoice running late (draft's ready), and
> your 2pm brief is below."

### On the Website

Ground every claim in the reader's actual week. Say the trust positions
plainly and proudly: your Stripe, your data, one price, one click to leave.

> "Three clients fit in your head. The ninety people who could refer you
> don't."

---

## Key Takeaway

YouSpot's voice is plain, warm, and quietly capable. Every sentence should
sound like a colleague who already did the reading — specific about people
and time, honest about where facts came from, and silent about pipelines,
teams, and its own intelligence.

**The product's whole promise is "no upkeep." Copy that demands attention it
didn't earn breaks the promise.**