# YouSpot Naming Guidelines

**Status: landed 2026-08-26.** Covers naming skills, features, and
surfaces, and writing their descriptions. The existing skill set
(`youspot_skills/` at the repo root) already follows a strong convention —
this doc makes it explicit so new names keep to it.

---

## The Wordmark

The product is **YouSpot** — capital Y, capital S, one word — everywhere a
person reads it. (`youspot` stays lowercase in code, paths, and package
names.) The corpus currently mixes "Youspot" and "YouSpot"; new writing uses
**YouSpot**.

---

## Core Naming Principles

### 1. The Name Is the Word You'd Say Asking for It

A name is right when it completes a natural sentence: *"brief me before this
call"*, *"chase that invoice"*, *"what's my warm list?"* If the reader has to
learn the name before they can use it, it's wrong.

### 2. One Word, Lowercase

The house style is a single lowercase word: `capture`, `recall`, `brief`,
`chase`, `reach`, `digest`. Hyphenate only when two words are genuinely
needed: `warm-list`, `intro-path`, `referral-yield`. Three words is a
sentence, not a name.

### 3. Name the Outcome, Not the Mechanism

`recall`, not "graph query." `capture`, not "ingestion pipeline." The
machinery stays behind the curtain; the name says what the person gets.

### 4. No Filler

Everything in YouSpot is automatic and AI-native — saying so is redundant.
Never: AI, smart, auto, magic, intelligent, advanced, ultimate, pro.

### 5. No Pipeline Vocabulary

Names obey the same banned list as copy (Constraint #4 in
[`../icp.md`](../icp.md)): no leads, deals, pipeline, funnel, scoring. The
product's dimensions are people, time, and warmth — names draw from there:
`warm-list`, `lapsed`, `reconnect`.

---

## The Canon

The shipped names are the pattern. Match them.

| Name | Why It Works |
|------|--------------|
| `capture` | The outcome (everything gets captured), one word, zero mechanism |
| `recall` | What you'd say: "what do I know about her?" |
| `brief` | Both noun and verb, and exactly what you get |
| `warm-list` | Two words earned: warmth is the product's native dimension |
| `intro-path` | The warmest route in — names the output, not the graph traversal |
| `chase` | What you'd mutter about the invoice |
| `reach` | Email everyone matching a description — the verb is the feature |
| `commitments` | Promises made and received; the plain word for it |
| `digest` | Arrives without being opened; named for what it is, not "insights" |
| `referral-yield` | The one metric name in the set, and it's *their* metric |

---

## Agents (ruled 2026-09-01)

Cloud agents are named for a directory a person scans, which is a different
job from naming a skill — so agents follow the agent naming formula, not the
one-word canon above:

```
[Primary Outcome or Domain] + [Task or Role]
```

Two to four words, the outcome or domain first, in the words the person would
say asking for it. The shipped set is the pattern: **Reconnect nudges ·
Meeting prep · New contact research · Commitment tracker · Inbox triage ·
Network updates.**

Two house rules still hold over the formula: **sentence case** (never
"Meeting Prep"), and the **banned vocabulary** below — an agent is never
named with leads, deals, pipeline, funnel, or scoring, whatever the formula
would allow. Digest and brief *headings* are unaffected: they stay
people-and-time ("What changed in your network"), per the writing style
guide.

## Names to Avoid

| Pattern | Example | Why It Fails |
|---------|---------|--------------|
| Filler words | "smart-recall", "auto-capture" | Everything here is automatic; the prefix admits doubt |
| Pipeline-speak | "lead-scorer", "deal-tracker" | Banned vocabulary; wrong product |
| Mechanism names | "graph-sync", "entity-resolver" | Names the plumbing, not the payoff |
| Clever wordplay | "The Network Whisperer" | Unclear, and the reader bills by the hour |
| Long compounds | "dormant-relationship-reactivation" | Not a word anyone would say |
| Platform generics | "dashboard", "insights", "workspace" | Could be any product; says nothing |

---

## Naming Checklist

Before a name ships, confirm:

- [ ] Does it complete a natural sentence? ("___ me before this call")
- [ ] Is it one word — or two, both earning their place?
- [ ] Is it lowercase?
- [ ] Does it name the outcome, not the mechanism?
- [ ] Is it free of filler (AI, smart, auto, magic)?
- [ ] Is it free of pipeline vocabulary?
- [ ] Would a consultant who's never seen YouSpot guess roughly what it does?
- [ ] Does it sit naturally next to the canon table above?

---

## Description Guidelines

### Lead with the Moment It Serves

Start with when the reader needs it, not what it computes.

**Bad:** "Assembles graph context and calendar metadata into a
pre-conversation document."

**Good:** "Walk into every call already caught up. Two minutes before,
`brief` pulls together who they are, what you last discussed, and what's
still open."

### Keep It Short

One value sentence, one how sentence, optional bullets. The reader skims.

```
[The moment it serves, as a promise]

[What shows up and where it came from]

- [What it reads — always "already happened" sources]
- [What the reader does — usually nothing, or one click]
- [The trust position, if one applies]
```

### Use Their Words

Write like you're explaining it to a consultant between calls.

| Instead of... | Say... |
|---------------|--------|
| "Leverages your communication graph" | "Reads your email and calendar" |
| "Automated re-engagement workflows" | "Drafts the note to someone who's gone quiet" |
| "Actionable relationship intelligence" | "Who to write to today, and what to say" |
| "Integrates with Stripe" | "Watches your Stripe — the money never touches us" |

### Be Specific, Not Vague

| Vague | Specific |
|-------|----------|
| "Stay on top of your network" | "The ninety people who could refer you, ranked by how long they've been quiet" |
| "Saves you time" | "The two minutes after every call, handled — the note writes itself" |
| "Never miss a follow-up" | "Promises made and received, tracked until they're kept" |

### Describe What Shows Up, Not What Runs

| Internal focus | What-shows-up focus |
|----------------|---------------------|
| "Scheduled graph computation traces revenue attribution" | "See which relationships your last three projects actually came from" |
| "Identity resolution across channels" | "The same Dana from email, LinkedIn, and your calendar — one person, one history" |

---

## Before/After Examples

### Example 1: warm-list

**Before:**
> "AI-powered contact prioritization engine using multi-signal relationship
> decay analysis."

**After:**
> "Who to write to today. Ranked by how long they've been quiet and how much
> work they've sent you — each with an opener already drafted."

---

### Example 2: chase

**Before:**
> "Automated accounts-receivable follow-up workflow with Stripe integration."

**After:**
> "The overdue-invoice email, drafted and calibrated to the relationship —
> firmer with the client who always pays late, gentler with the one who
> never does. The money never touches us."

---

### Example 3: capture

**Before:**
> "Omnichannel ingestion pipeline with entity resolution and timestamped
> edge creation."

**After:**
> "Everything that already happened — email, calendar, calls — becomes the
> record on its own. You never type a note twice."

---

## Style Rules

### Skill names are lowercase in copy
- ✓ "the warm-list shows who's been quiet longest"
- ✗ "Warm-List shows..."

### The wordmark is YouSpot
- ✓ "YouSpot reads what already happened."
- ✗ "Youspot" / "YouSpot™ Platform"

### Active, specific phrasing
- ✓ "Drafts the reconnect from your own sent mail"
- ✗ "Can help you potentially re-engage dormant contacts"

### Match the YouSpot voice
Plain, warm, quietly capable. See [`brand-voice.md`](brand-voice.md) and
[`writing-style-guide.md`](writing-style-guide.md).

---

## Quick Reference

| Element | Pattern | Example |
|---------|---------|---------|
| **Name** | The word you'd say asking for it | `brief` |
| **Description line 1** | The moment it serves | "Walk into every call already caught up." |
| **Description line 2** | What shows up, from where | "Who they are, what you last discussed, what's still open." |
| **Optional bullet** | The trust position | "Reads what already happened — you never type a note." |