Skills/glossary/SKILL.md

---
name: glossary
description: Use when adding, changing, or removing a glossary entry (maintain), or building a new glossary for an existing project from its prose surface (bootstrap). The skill applies the rules in docs/glossary-convention.md — it restates none of them. maintain keeps the existing user-any-time / boss-record-reality write authority and adds a conformance check; bootstrap is user-only (high-context multi-agent work; boss may recommend it via bounce-back but never runs it).
---

# glossary — build and maintain a project's glossary

> **Violating the letter of these rules is violating the spirit.**

## Overview

A project's glossary pins canonical nomenclature so terminology does not
drift over time, and so LLM-driven work reuses the established term for a
concept instead of coining a fresh synonym each session.
`../docs/glossary-convention.md` owns the rules — the three-field format,
the reading obligation, the record-reality write-rule, and the
glossary-as-source-of-truth declaration. This skill is the *procedure*
that applies those rules; it restates none of them.

It carries two procedures. **maintain** adds, changes, or removes a
single entry under a conformance check. **bootstrap** builds a fresh
glossary for a project that has none, by fanning out read-only
`glossary-extractor` agents over the project's prose surface and
synthesising their observations into conforming entries.

## When to Use / Skipping

Triggers:

- **maintain** — a term is to be added, changed, or removed in an
  existing glossary, by the user any time, or by boss to record reality
  (a term already in consistent use, or a drift boss just resolved).
- **bootstrap** — a project has terminology to pin but no glossary (no
  glossary path in its CLAUDE.md project facts, or the named file is
  empty), and the user invokes the build.

Skip or refuse:

- maintain asked when the project's CLAUDE.md project facts name no
  glossary path: there is nowhere to write. Stop and instruct the user to
  record the glossary path in the project's CLAUDE.md first.
- bootstrap asked on a glossary that already has entries: do not clobber.
  Stop with the entry count and recommend maintain.
- bootstrap asked in a boss (autonomous) session: refuse. bootstrap is
  user-only; boss may recommend it via bounce-back but never runs it (see
  Authority).

## Authority

maintain inherits the existing write authority unchanged
(`../docs/glossary-convention.md` § Extending): the user any time; boss
autonomously but only to record reality, never to invent. This skill adds
the conformance check around that authority; it does not widen it.

bootstrap is **user-only**. It is high-context multi-agent work analogous
to a fresh `brainstorm`, which boss bounces back rather than starting
autonomously. In a boss session, recommend a bootstrap via bounce-back
when a project lacks a glossary and drift is visible — do not run one.

## Mode dispatch

On invocation, route on the argument:

- `maintain` (or `add` / `change` / `remove`) → the maintain procedure.
- `bootstrap` → the bootstrap procedure (user-only).

If the mode is ambiguous, ask once; do not guess.

## The maintain procedure

1. **Read the glossary and the convention.** Read the glossary file the
   project's CLAUDE.md project facts name, plus
   `../docs/glossary-convention.md`. If the project facts name no glossary
   path, stop (see When to Use / Skipping).
2. **Take the proposed entry.** A canonical-term heading, an `**Avoid:**`
   line, and a definition — the user's, or (in a boss session bound by
   record-reality) the term already in consistent use.
3. **Run the local conformance check** against the proposed entry and the
   rest of the glossary:
   - the three-field shape the convention defines;
   - the definition is at most two sentences;
   - collision scan: the proposed canonical term must not already sit
     under another entry's **Avoid**, and a proposed **Avoid** synonym
     must not be another entry's canonical term.
   On any failure, REJECT — name the violated rule, do not write the
   entry, and ask for a corrected one.
4. **Run the stale-usage sweep** (on add / change / rename): grep the
   prose surface for the old canonical term (change/rename) and for each
   **Avoid** synonym, and report the hits as drift the user may want to
   fix. The sweep reports; it does not block — guidance, not enforcement.
5. **Write the conforming entry UNSTAGED.** Add, edit, or remove the
   entry in the glossary file, preserving the flat per-term-block shape so
   the diff stays line-wise clean. Leave it unstaged for review.
6. **Hand back** to the user for review. In a boss session, the
   record-reality discipline governs whether the write was permitted at
   all (boss never coins).

## The bootstrap procedure (user-only)

1. **Guard.** Read the glossary path from the project's CLAUDE.md project
   facts. If it names a file that already has entries, stop with the count
   and recommend maintain. If the project facts name no glossary path,
   continue, and note the build will also propose recording one in the
   project's CLAUDE.md.
2. **Partition the prose surface into slices** — the readable prose of
   the project: `docs/`, `README.md`, the project's design ledger, if it
   has one (its CLAUDE.md project facts). Exclude `docs/specs` and
   `docs/plans` — those are ephemeral active-cycle artefacts, not durable
   prose (see `../docs/conventions.md` § Lifecycle).
   One slice per coherent group, sized so a single agent can sweep it.
3. **Fan out one `glossary-extractor` per slice.** Dispatch the read-only
   agent (`agents/glossary-extractor.md`) with the carrier: the slice and
   the extraction task. Agents do not nest; the skill curates each
   carrier.
4. **Merge and cluster.** Collect the reports. Cluster variants that name
   the same concept across slices, summing frequencies.
5. **Synthesise.** For each cluster:
   - a clear cluster (one dominant variant) → auto-include it as a
     conforming entry: canonical heading = the dominant variant,
     **Avoid** = the other variants, a ≤2-sentence definition drawn from
     the observed usage;
   - a contested cluster (≥2 comparable variants) → surface it to the user
     with the variants, frequencies, and locations, and ask which is
     canonical. Never decide a contested canonical yourself.
6. **Handle the unresolved.** A contested cluster the user does not
   resolve is left OUT of the glossary and noted as deferred. Never coin a
   term to fill a gap.
7. **Assemble UNSTAGED.** Write the conforming glossary to the path the
   project's CLAUDE.md project facts name (proposing one if none is
   recorded yet), in the convention's flat per-term-block format. Leave it
   unstaged for review.

## Iron Law

```
THE CONVENTION OWNS THE RULES; THIS SKILL ONLY APPLIES THEM — RESTATE NOTHING.
A NON-CONFORMING ENTRY IS REJECTED, NOT WRITTEN.
BOOTSTRAP IS USER-ONLY. NEVER COIN A TERM — RECORD REALITY.
```

## Handoff Contract

| Direction | Carrier |
|-----------|---------|
| user → glossary (maintain) | the proposed entry + the operation (add / change / remove) |
| user → glossary (bootstrap) | the build request |
| glossary → glossary-extractor (bootstrap) | one prose slice + the extraction task |
| boss → user (bounce-back) | a recommendation to run a bootstrap; boss never runs one itself |

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| "The entry is obviously fine, skip the conformance check" | The check is the skill's whole reason to exist over hand-editing. Run it. |
| "Two variants are close; I'll pick the more frequent as canonical" | A contested cluster is a nomenclature judgement that belongs to the user. Surface it; do not decide it. |
| "The concept clearly needs a term, I'll coin one" | The glossary records reality, never invents. An unresolved concept is left out and deferred. |
| "boss is running and the project has no glossary, I'll bootstrap it" | bootstrap is user-only. Recommend it via bounce-back; do not run it. |
| "I'll restate the format here so the skill is self-contained" | The convention is the single source for the rules. Cite it; restating it is the cross-doc drift this split exists to prevent. |
| "The stale-usage hits should block the write" | The sweep is guidance, not enforcement. Report the drift; write the entry regardless. |

## Red Flags — STOP

- About to write a non-conforming entry instead of rejecting it.
- About to pick a canonical term for a genuinely contested cluster.
- About to coin a term for a concept that has no observed term.
- About to run a bootstrap in a boss / autonomous session.
- About to restate the convention's format or write-rule in this file.
- About to clobber a populated glossary with a bootstrap.

## Cross-references

- **Rules (the single source):** `../docs/glossary-convention.md` —
  format, reading obligation, write-rule, glossary-as-SoT. This skill
  applies these; it restates none.
- **Glossary path:** the project's CLAUDE.md project facts — when they
  name a glossary path it is standing reading for every role; when they
  name none, this skill has nowhere to write and bootstrap proposes one.
- **Agent dispatched:** `agents/glossary-extractor.md` — read-only
  per-slice prose extraction, fanned out in bootstrap.
- **Glossary instance (dogfood):** `../docs/glossary.md` — this plugin's
  own glossary.
- **boss write authority:** `../boss/SKILL.md` — the record-reality rule
  for the only autonomous glossary writer, and the bootstrap bounce-back.