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
  (`paths.glossary` unset, or naming an empty file), and the user invokes
  the build.

Skip or refuse:

- maintain asked with no `paths.glossary` slot set: there is nowhere to
  write. Stop and instruct the user to set `paths.glossary` (see
  `../docs/profile-schema.md` § `paths`) 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 file named by
   `paths.glossary` and `../docs/glossary-convention.md`. If
   `paths.glossary` is unset, 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 `paths.glossary`. If it names a file that already has
   entries, stop with the count and recommend maintain. If the slot is
   unset, continue, and note the build will also propose setting the slot
   (see `../docs/profile-schema.md` § `paths`).
2. **Partition the prose surface into slices** — the readable prose of
   the project: `docs/`, `README.md`, the design ledger (if
   `paths.design_ledger` is set), the spec directory. 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
   `paths.glossary` (proposing the slot value if it was unset), 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.
- **Slot semantics:** `../docs/profile-schema.md` § `paths` — the
  `paths.glossary` slot (set ⇒ standing reading for every role; unset ⇒
  no-op).
- **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.