glossary · diff
git:20260511.513500e to git:20260514.f4c27cf
230 added, 65 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: glossary
description: >-
Project glossary for consistent domain terminology. Invoke whenever task
involves creating, updating, or referencing a glossary, defining domain
terms, establishing ubiquitous language, or when inconsistent naming
causes confusion in code or planning artifacts.
---
# Glossary
- Consistent terminology prevents agents from inventing names. 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 is structural context that lives alongside agent instructions, consumable by both humans and agents as a single
- source of truth for project vocabulary.
+ 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.
- ## Creating a Glossary
+ 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.
- ### Phase 1 — Identify Scope
+ 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.
- 1. Determine whether the project needs one glossary or multiple per bounded context.
- - Single glossary: projects with one domain, one team, one codebase.
- - Per-context glossaries: projects with distinct subdomains where the same word means different things (e.g., "Order"
- in billing vs fulfillment).
- 2. For per-context projects, name each bounded context and create a separate glossary file per context.
+ ## Scope
- ### Phase 2 — Extract Terms
+ Decide how many glossaries the project needs:
- Interview the user to extract domain knowledge. Focus on:
+ - **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.
- - **Core entities** — what are the main "things" in this domain? What states do they transition through?
- - **Business events** — what triggers state changes? What are the verbs?
- - **Value objects** — what data is immutable and identified by content, not by ID?
- - **Enum values** — what are the specific allowed values for categorical fields? Define them upfront so generated code
- matches the domain model exactly.
- - **Aliases to prohibit** — for each term, what synonyms might an agent use that would be wrong? "Session" when the
- domain says "Run". "Permission" when the domain says "Governance Check". This column prevents naming drift.
- - **Architectural names** — services, modules, patterns that have specific names in this project.
+ ## Selecting Terms — the trap test
- ### Phase 3 — Format
+ 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.
- Format each glossary as a markdown table with four columns:
+ **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
- | Term | Definition | Aliases (AVOID) | Related Terms |
- | --- | --- | --- | --- |
- | Order | Aggregate representing a customer's commitment to purchase. States: Draft → Placed → Paid → Fulfilled → Cancelled | Purchase, Transaction, Sale | LineItem, Customer |
- | Governance Check | Validation before each tool call. Four phases: allowlist, registry status, connection health, policy budget | Permission Check, Access Control, Authorization | Run, Tool Registry |
- | CompletionReason | Value object. Enum: `user_ended`, `inactivity_timeout`, `step_limit_reached`, `tool_call_limit_reached`, `duration_limit_reached` | EndReason, StopReason | Run |
+ # [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 "Aliases (AVOID)" column is the highest-value field — it tells agents what NOT to call things, which is as important
- as what to call them.
+ 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.
- ### Phase 4 — Place
+ ## Per-entry format
- Store glossary files in the project alongside agent instructions:
+ ```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 exposes boundary
+ cases the definitions missed — especially useful when two concepts could plausibly be confused:
+
+ ```markdown
+ ## Example usage
+
+ > **Reviewer:** Why is this job re-released on every loop?
+ > **Author:** That's the **aggregation gate**. **Re-release** is the mechanism — not a retry. The bucket stays open
+ > while the gate says new events are still arriving.
+ > **Reviewer:** So flush only happens after `MaxAccumulationTime`?
+ > **Author:** Or after `ReReleaseInterval` of silence — both conditions matter.
+ ```
+
+ ## Placement
+
- **Single glossary:** `docs/glossary.md` or `docs/ubiquitous-language/glossary.md`
- - **Per-context:** `docs/ubiquitous-language/{context}-glossary.md` (e.g., `billing-glossary.md`,
- `orchestration-glossary.md`)
- - **Reference from CLAUDE.md:** add a pointer early in the file (top sections) so the glossary is discoverable. Early
- placement exploits primacy attention — standards positioned at the start of context reduce naming violations by
- 35-40%. Do not inline the glossary in CLAUDE.md — use progressive disclosure:
+ - **Per-context:** `docs/ubiquitous-language/{context}-glossary.md` (e.g., `billing-glossary.md`)
+ - **Reference from CLAUDE.md** early — primacy attention reduces naming violations significantly. Do not inline the
+ glossary in CLAUDE.md; use progressive disclosure:
```markdown
## Domain Vocabulary
+
See `docs/glossary.md` for project terminology and prohibited aliases.
```
- ## Referencing a Glossary
+ ## Referencing a glossary
- When invoked to look up or apply terminology (not to create or update):
+ When applying terminology (not creating or updating):
- 1. Locate the glossary file(s) — check `docs/glossary.md`, `docs/ubiquitous-language/`, or ask the user.
- 2. Read the glossary and find the relevant term(s).
- 3. Apply the correct name and actively avoid the listed aliases. If the requested concept isn't in the glossary, flag
- the gap — this is a trigger for an update.
+ 1. Locate the glossary — check `docs/glossary.md`, `docs/ubiquitous-language/`, or ask the user.
+ 2. Read it and find the relevant term(s).
+ 3. Use the canonical name; actively avoid the listed `Avoid` entries.
+ 4. If the concept isn't in the glossary, **run the trap test before adding it**. Not every absent term belongs. Most
+ project nouns are not naming traps and should stay out.
- ## Updating a Glossary
+ ## Updating a glossary
- Glossary maintenance is event-driven, not scheduled:
+ Maintenance is event-driven, not scheduled:
- - **Agent naming mistake:** when an agent uses a wrong name that better context would have prevented, add or update the
- term immediately. The mistake is the trigger.
- - **New feature / bounded context:** when new domain concepts emerge during DRAFT stages, add them before
- implementation. Discovery and alignment naturally surface new terms — capture them in the glossary when they appear.
- - **Term meaning shift:** when a term's definition changes, update the definition and add a brief note about what
- changed and when. The glossary is a living artifact.
+ - **Naming mistake — yours, the model's, or a reviewer's:** add or update the term immediately. The mistake is both the
+ trigger and the source of the `Avoid` rationale — write down which name was reached for, and why it's wrong.
+ - **New domain concept emerges:** add during discovery or alignment, but only if it passes the trap test.
+ - **Meaning shifts:** update the definition in place. Don't keep a changelog — the glossary is current truth.
+ - **Term renamed but legacy code still uses the old name:** keep the entry; add
+ `**Deprecated:** prefer [NewName] — [one-phrase reason]` at the top of the definition. Delete the entry once the
+ codebase is clean. This is the one acceptable exception to the no-changelog rule — the marker is operational, not
+ historical.
+ - **Entry has no live trap anymore:** delete it. Stale "obvious" entries normalize bloat and dilute the signal of the
+ remaining entries.
- Do not create a new file for each update. Edit in place. The glossary is a single source of truth, not a changelog.
+ Edit in place. The glossary is single source of truth, not a versioned document.
+ ## Re-running
+
+ When invoked again on the same project:
+
+ 1. Read the existing glossary file in full.
+ 2. Incorporate new terms surfaced since last invocation.
+ 3. Update definitions whose understanding has evolved.
+ 4. Re-flag any new ambiguities; remove ambiguities that have been resolved.
+ 5. Delete entries that no longer pass the trap test.
+
+ A re-run is not an append. It is a re-derivation that may shrink the glossary as well as grow it.
+
## Rules
- - **Separate file, not inline.** The glossary lives in the project filesystem, not embedded in CLAUDE.md or conversation
- context. Agents and humans reference the same file.
- - **Four-column table.** Term, Definition, Aliases (AVOID), Related Terms. The aliases column is mandatory — without it,
- agents will invent synonyms.
- - **One glossary per bounded context.** If the same word means different things in different parts of the system, split
- into separate glossaries. Agents should load only the vocabulary relevant to their current scope.
- - **Living artifact.** Updated when mistakes reveal gaps, when new terms emerge, when definitions evolve. Not versioned
- by date — a single file that represents current truth.
- - **Consumable by both humans and agents.** Markdown table format is readable in any editor and parseable by any LLM.
- Avoid YAML/JSON unless the project specifically needs machine-parsed structured data.
+ - **Heading per term, never tables.** Tables collapse multi-line definitions and rationale-bearing `Avoid` lines. Each
+ entry is independent; KV/heading is the right primitive.
+ - **Trap test before inclusion.** If no plausible-but-wrong name exists, the entry doesn't exist.
+ - **`Avoid` lines carry rationale.** Synonyms without "why it's a trap" rarely teach.
+ - **Required intro paragraph.** Every glossary states its selectivity contract up front.
+ - **Separate file, not inline.** Lives in the project filesystem; humans and agents reference the same file.
+ - **One glossary per bounded context.** Same word, different meanings → split into separate files.
+ - **Living artifact, not a changelog.** Edit in place. Delete entries that stop earning their place.
+ - **Consumable by humans and agents.** Markdown headings + prose work in any editor and parser. Avoid YAML/JSON unless
+ the project needs machine parsing.
+ ## Worked example
+
+ A well-formed glossary fragment for a Gerrit-event → chat-message notifier:
+
+ ````markdown
+ # Notifier 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.
+
+ ## Pipeline Concepts
+
+ ### Source
+
+ A _named_ Gerrit instance — the key under `gerrit.sources` in config. Embedded in the webhook URL and in every cache
+ key. Multi-tenant isolation is load-bearing: never collapse this axis because "we only have one Gerrit."
+ **Avoid:** Gerrit (ambiguous with the product — the _instance_ is one of potentially many); Backend (suggests a
+ storage/persistence layer it isn't).
+
+ ### Atomic Event
+
+ A single Gerrit webhook event carried as one queue job. Lives only long enough to be parsed, matched to subscribers,
+ and pushed into a Logical Event cache. The atomic/logical split is not optional — collapsing them collapses the
+ aggregation window.
+ **Avoid:** Raw event (sounds like an unparsed payload — but it's already parsed); Gerrit event (Gerrit emits many
+ event _types_; "atomic" names the unit, not the source).
+
+ ### Re-release
+
+ Returning a beanstalkd job to its tube so it is reserved again later. In this project it is the **normal aggregation
+ mechanism**, not an error path — atomic-job re-releases enforce the per-job delay cycle; logical-job re-releases keep
+ the bucket open.
+ **Avoid:** Retry (implies error recovery — the most common and most damaging misnomer here); Requeue (suggests a
+ separate queue when it's the same tube).
+ ```
+ ````
+
+ Notice what is **not** in this fragment: `MultiClient`, `EventSampler`, `BeanstalkJobDelay`, `Workbench`. They are
+ config or implementation details documented in code and have no plausible-wrong name. They fail the trap test.
+
## Related Skills
- - **discovery** — surfaces domain terms during questioning; trigger for initial glossary creation
- - **alignment** — pattern surfacing may reveal naming inconsistencies to resolve
- - **diagramming** — domain models and context maps complement the glossary visually
+ - **discovery** — surfaces domain terms during questioning; trigger for initial glossary creation.
+ - **alignment** — pattern surfacing may reveal naming inconsistencies worth recording.
+ - **diagramming** — domain models and context maps complement the glossary visually.