glossary

What this skill does

# Glossary

A glossary prevents naming drift on the small set of terms where drift is likely. It is **not** a project dictionary —
not every domain concept belongs. The highest-leverage element of each entry is the **rationale on the `Avoid` line**:
what plausible-but-wrong name would a reviewer or agent reach for, and why is it a trap? Without that rationale, the
entry teaches nothing.

LLMs are amplifiers — give them a clear vocabulary and they generate coherent structure; give them a codebase where the
same concept has four names, and they'll invent a fifth. The glossary makes the choice for them.

A glossary's real failure mode is disuse. If it isn't the document a reviewer reaches for during naming disagreements,
no amount of format polish saves it. Every rule below — the trap test, rationale-bearing `Avoid` lines, the CLAUDE.md
pointer — exists to make the glossary worth opening.

## Scope

Decide how many glossaries the project needs:

- **Single glossary** — one domain, one team, no terms with double meanings across the codebase.
- **Per-bounded-context** — the same word means different things in different parts of the system (e.g., `Order` in
  billing vs fulfillment). In DDD terms, each bounded context speaks its own dialect of the ubiquitous language; one
  glossary per dialect. Create one file per context; name each context explicitly.

### Context map (multiple contexts only)

A per-context glossary defines terms _within_ its dialect, but the relationships _between_ contexts — which context
emits an event another consumes, which value types they share — live in no single glossary. When a project has several
context glossaries, an optional `docs/ubiquitous-language/context-map.md` names each context with a one-line purpose and
the directional flows between them:

```markdown
## Contexts

- **Ordering** — places and tracks customer orders.
- **Fulfillment** — picks, packs, ships.

## Relationships

- Ordering emits `OrderPlaced`; Fulfillment consumes it.
- Ordering and Billing share `CustomerId` and `Money`.
```

Add it only when multiple contexts genuinely exist and the cross-talk is not obvious from the names. It is prose, not a
table, and it complements — does not replace — a context-map _diagram_ (see the `diagramming` skill).

## Selecting Terms — the trap test

For each candidate term, apply the trap test: **would a reviewer or agent plausibly reach for a wrong name here?** If
the only name anyone would use is the canonical one, omit the entry. The glossary's job is naming-drift prevention, not
domain documentation.

**Where to look — discovery is evidence-driven, not enumeration-driven:**

- Naming disagreements in this conversation or recent code review.
- Mismatches between code identifiers and how the team speaks ("we call it the sync worker; the code says
  `gerrit-events-consumer`").
- Library or SDK terms that bleed into local code with a different meaning (third-party `Job` vs project `Task`).
- Words used for two distinct concepts in the same discussion (live overload).
- Discovery or alignment artifacts (when invoked inside the DRAFT pipeline).
- Postmortems or incident reports mentioning "we thought X meant Y" or "the rename caused…".

"Find every entity, event, and value object" reliably produces overcollection — most candidates won't pass the trap test
anyway. Start from evidence of confusion, then filter.

**Worth including:**

- Terms with multiple plausible names where the wrong one is genuinely tempting.
- Canonical names that conflict with a stronger natural name — the system says `Source`, but everyone says `Gerrit`.
- Concepts that look like another concept — the system's `Re-release` reads as `Retry` to anyone not steeped in it.
- Overloaded primitives — a single event type routed to two different domain buckets, where the routing logic is
  non-obvious from the name.
- Aliases that exist in upstream APIs or libraries and bleed into local code (e.g., a third-party SDK calls it `Job`,
  the project calls it `Task`).

**Worth omitting:**

- Terms with one obvious name and no synonym pressure — no plausible wrong name → no trap → no entry.
- Implementation details — config field names, struct names, internal helpers. These belong in code documentation, not
  the glossary.
- External services with one canonical name in the company.
- Generic programming concepts (array, function, endpoint) unless they have a project-specific meaning.

The selectivity rule is load-bearing. A glossary that lists everything trains the next pass to add more "for
completeness," and the bloat compounds. Restraint at creation defends against bloat at maintenance.

## Required intro paragraph

Every glossary opens with a 2–3 sentence scope statement. This deflects "why isn't X here?" from readers and calibrates
the `Avoid` criterion for downstream consumers:

```markdown
# [Project] Glossary

Project vocabulary. Only entries with a real risk of being mis-named are listed; everything else is in
[CLAUDE.md](../CLAUDE.md). For each term, **Avoid** lists the synonyms that are realistic naming traps — names a
reviewer or agent would plausibly reach for and get wrong.
```

The intro is not boilerplate — it is the contract between the glossary and its readers. Adapt the wording to the
project, but keep the two contractual statements: (1) the selectivity criterion, and (2) what `Avoid` means.

## Per-entry format

```markdown
### TermName

1–3 sentences defining what the term **is**, not what it does. Carry nuance — three kinds, four phases, an "and not"
clarification. No need to compress to one line.
**Avoid:** WrongName₁ (one-phrase rationale — what trap this name sets); WrongName₂ (rationale).
```

**Definition rules:**

- Define **what it is**, not what it does. "An aggregated bucket of atomic events for a `(source, chat, project, actor)`
  tuple" — not "the thing created when events are aggregated."
- Carry the nuance a one-liner would lose. Multi-clause definitions are fine; the heading format is chosen for exactly
  this.
- Do not list "see also" or "related terms" inline. They produce a low-value reference web. If cardinality matters, use
  the optional Relationships section.

**`Avoid` rules:**

- Each entry on the `Avoid` line **must** carry rationale in parentheses. Bare synonym lists ("Purchase, Transaction,
  Sale") rarely teach — the reader still doesn't know which trap is worth worrying about. With rationale ("Retry —
  implies error recovery, which this is not"), the entry becomes a calibration anchor.
- If a term has no realistic naming trap (no candidate `Avoid` entries), question whether the term belongs in the
  glossary at all. Most "no-trap" entries should be deleted, not entered without `Avoid`.

## Optional sections

Include only when the project genuinely benefits. Each one earns its place; don't bolt them on by default.

### Grouping by subdomain

When entries cluster naturally — Pipeline Concepts, Subscription Model, External Boundaries — use H2 headings to group
them. A flat list works for small glossaries. Don't force groupings on five entries.

### Flagged ambiguities

When the conversation or codebase actually uses one word for two concepts, call it out:

```markdown
## Flagged ambiguities

- "Account" is used in code for both **Customer** (places orders) and **User** (auth identity). These are distinct
  concepts; new code should not introduce `Account` without a disambiguating suffix.
```

Include only when a live conflict exists. Do not add an empty section as a placeholder.

### Relationships

For terms with non-obvious cardinality:

```markdown
## Relationships

- An **Invoice** belongs to exactly one **Customer**.
- A single **Order** can produce many **Invoices** — one per **Shipment**.
```

Narrative sentences, not a column. Skip when relationships are obvious from the entries themselves.

### Example usage

A short dialogue or 2–4 sentence narrative showing terms in natural use. Calibrates the register and