# WRITING.md
## Microcopy in the product

> Marketing voice is sharp. Product voice is **direct**.
>
> No personality. No apology. No hedging. The user did something; the system answers.

This document is for anyone typing a button label, an empty state, an error, a toast, or a loading message. It is the floor — write better than this when you can; never write worse.

If you can't decide between two options, pick the one that has fewer words and more nouns.

---

## §1 · Voice in product (vs marketing)

| | Marketing voice | Product voice |
|---|---|---|
| Job | Earn attention | Don't waste it |
| Length | One sharp sentence | Two or three nouns |
| Tone | Confident, written | Flat, observational |
| Example | "Stop guessing what humans will do." | "Run finished. Net revenue +3.4%." |

The product is talking to someone who is **already inside.** They have given us their attention. The job is to return it as fast as possible.

---

## §2 · Buttons

**Action-first verb. Always concrete. Never the word "Submit."**

Approved primary verbs:

```
Save · Run · Stop · Continue · Open · Close
Delete · Cancel · Export · Share · Invite
Sign in · Sign out · Create · Duplicate
Connect · Disconnect · Resume · Retry
```

**Destructive actions carry the noun:**

| Don't | Do |
|---|---|
| Delete | Delete run · 38 |
| Remove | Remove member · avi@ |
| Cancel | Cancel run |
| Reset | Reset audience |

**Cancel is always the secondary, never the primary.** It's ghost text or a transparent button — never competing for the eye with the commit.

**Banned button labels:**
- Submit
- Click here
- OK
- Yes / No
- Done (when it doesn't actually finish anything)
- Got it
- Continue (without saying continue *to what*, when ambiguous)

---

## §3 · Errors

**Three-part format: what · why · what to do.**

> **Run failed**
> Stopped at agent 412 of 2,047 — model timeout. No charge applied.
> [Resume from checkpoint] · [View incident report]

The first line names the event. The second names the cause and the cost. The third gives the user the next move — as a link, never a "Submit" button.

**Banned words in errors:**
- Oops
- Sorry
- Whoops
- Uh-oh
- Something went wrong
- An unexpected error occurred
- Please try again later

If you don't know what happened, say *that*: "We don't know why this failed. The trace ID is xxx. Email support and we'll find out within an hour."

**Never blame the user.** "Your file is invalid" is acceptable; "You uploaded an invalid file" is not. The system is reporting on its own state, not on the user's competence.

---

## §4 · Empty states

**Three-part format: what this is · why it's empty · one CTA.**

> **No simulations yet.**
> Your library will fill up here. Start by describing a decision in plain English — population, horizon, outcome.
> [New simulation ↗]

Three flavors:

- **Zero state** — they've never had any. Tell them what would be here.
- **No-results state** — their filter found nothing. Suggest the closest match.
- **Error state** — we have it, we can't show it. Offer retry or duplicate.

**Banned:**
- "No data."
- "There's nothing here yet!"
- Cartoon illustrations of empty boxes, magnifying glasses, or astronauts.
- A CTA that just says "Get started."

---

## §5 · Loading states

By duration:

| Duration | Treatment | Copy |
|---|---|---|
| < 1s | Silent | None |
| 1–4s | Spinner | Verb-noun: "Saving spec," "Verifying audience" |
| 4–30s | Determinate progress bar | "Run · 38 · 62% · 1m 24s left" |
| > 30s | Determinate + status updates | Update the verb-noun every 10s |

If the wait will exceed 30 seconds, name the typical: "This usually takes 4 minutes."

If the wait exceeds the typical, **acknowledge it**: "This is taking longer than usual — about 9 min remaining."

**Banned:**
- "Loading…" with no other context
- A progress bar with no percentage and no time
- A spinner that has been on screen for longer than 4 seconds

---

## §6 · Confirmations

**Only for destructive + irreversible actions.** Reversible actions never get a confirmation — they get an undo.

Two buttons. The action verb (carrying the noun) goes on the right. "Cancel" goes on the left as ghost text.

> **Delete run · 38 and 2,047 agent traces?**
> The result, the cohort breakouts, and every agent's reasoning trace will be removed permanently. The intake spec will stay in your library so you can re-run it.
> [Cancel] · [Delete run · 38]

**Banned:**
- "Are you sure?"
- Yes / No
- "OK" as the destructive button
- "Don't show this again" — every destructive confirmation earns its interruption.
- A third button.

---

## §7 · Toasts

A toast is a **receipt** for an asynchronous action. Not a notification. Not an announcement.

Format: `[noun · verb] [one sentence] [optional remediation link]`

> ● **Saved** — spec saved to your library as "Pro $29 → $49"
> ● **Running** — 2,047 agents · est. 4 min remaining (auto-dismiss in 7s · click to pin)
> ● **Failed** — Run · 38 stopped at agent 412 · model timeout. [Retry the simulation]

Timing:
- **Success** auto-dismisses at **4s**.
- **Info** auto-dismisses at **7s**.
- **Warn / error** persist until acknowledged.

**Don't toast a successful click.** ("Saved!" "Copied!" "Done!") The next state is the receipt.

---

## §8 · Numbers, dates, units

- Tabular nums always (`font-variant-numeric: tabular-nums`).
- Currency: `$499.00`, `$1,499`, `$1.4M`, `$1.4B`. Two decimals when the value is *exactly* known; round when projecting.
- Percentages: `3.4%`, `+3.4pt` for percentage-point deltas (never "3.4 percentage points").
- Time: `4m 12s` not "4 minutes 12 seconds". `26.04 14:02` for absolute timestamps in product (we use the European format because it sorts cleanly).
- Counts: `2,047` (comma-separated) for exact; `2k` / `2.1k` for approximate; `1M`, `15M`, `1B` for hero numbers.
- Ranges: `$39 → $49`, `2 – 4 min`, `Q3 2026`. Em-dash never gets spaces in a range; en-dash with spaces is acceptable for date ranges.
- Units have **no space** before `%`, `pt`, `pp`. Space before `min`, `s`, `ms`.

---

## §9 · The forbidden words list

These words signal that the writer was reaching for personality instead of clarity. Strike them on sight.

```
just · simply · easily · quickly · effortlessly
please · sorry · oops · whoops · uh-oh
hey · hi there · friend · folks · y'all
let's · we'll · let me · I'll
amazing · awesome · great · wonderful · perfect
you've got this · you're all set · way to go
```

Two patterns to avoid:

- **The fake-friend opener.** "Hey there!" "Welcome back!" The product is not a person; it does not need to greet.
- **The reassuring hedge.** "Don't worry," "no problem," "it's all good." If there is a problem, name it. If there isn't, say nothing.

---

## §10 · Examples gallery

| Don't | Do |
|---|---|
| Oops! Something went wrong. | Run failed at agent 412 — model timeout. No charge applied. |
| Are you sure you want to delete this? | Delete run · 38 and 2,047 agent traces? |
| ✓ Looks good! | *(no copy — show the next state)* |
| Welcome back, friend! | *(no copy — show the dashboard)* |
| Click here to learn more. | Read the methodology ↗ |
| Please enter a valid email. | This isn't an email address — we expected one with an @ in it. |
| No data. | No simulations yet. Your library will fill up here. |
| Loading… | Verifying audience · 2,047 agents matched. |
| Submit | Run simulation ↗ |
| Yes / No | Cancel · Delete run · 38 |

---

## §11 · The 90-second checklist

Before shipping any string, ask:

1. Does it say what happened, in a noun + verb?
2. Did I use any forbidden word? (Strike it.)
3. Is there a "please" or "sorry"? (Strike it.)
4. If destructive: does the verb carry the noun?
5. If error: does it say what · why · what to do?
6. Is there a number? Is it tabular? Is the unit attached?
7. Could I cut a word and still be understood? (Cut it.)

If you answered yes to 7, the string is ready to ship.

---

## §12 · Marketing voice: the causal register

Product voice is flat (§1). Marketing voice is sharp, and it argues one thing:
causation. The category sentence, repeatable from memory:

> Subconscious is the causal AI company. Randomized experiments on a simulation
> of your market, validated against real human behavior, tell you why people
> choose and which action drives the outcome.

### Lexicon we own (use in headlines)
causal · cause · why · randomized experiment · intervention · replication ·
human baseline · holdout · confidence interval · error bars · say-do gap ·
prescriptive · "which action"

### Lexicon we cede (never self-describe with these)
insight(s) · listening · signals · experience (management) · digital twins ·
clones · personas · synthetic respondents · panels · world model ·
"age of simulation" · agentic · AI-powered

"Simulation" is the lab bench, not the product: use *simulate* as a verb inside
the mechanism sentence, never as the category noun.

### Proof grammar (every external claim)
claim + number + source + limitation. Never borrow a number. Never round 93 to
95. Lead with the leaderboard's existence, not a flattering cut of it. Publishing
mid-range scores and failure modes is the differentiator no competitor copies.

### No AI tells

No em-dashes inside marketing sentences. The interruption pattern (claim —
qualifier — payoff) is the most recognizable machine-written tell. Use a period
and a new sentence, or a colon. A term list may use the dash as a separator; a
sentence may not use it as a pivot.

No AI vocabulary: delve · robust · seamless · comprehensive · leverage ·
unlock · supercharge · elevate · transform · empower.

Short declaratives beat clause-chains. Read it aloud. If it sounds like a press
release, cut it. The house cadence is "Not descriptive. Not predictive.
Prescriptive."

### Forbidden in marketing copy
"leader in …" (unless defined concretely) · revolutionize · AI-powered ·
"insights" as the name of our output (say answers, estimates, causal maps) ·
any superlative without number + source · any accuracy figure not in the
evidence pack.

---

*Authority for this document: the product team. Disagreements about a specific string get resolved by the principle in §1 — the user is already inside, return their attention quickly.*