What it does
bootstrap-glossary reads the vocabulary a codebase has already committed to: type, class and
table names first, then module and directory names, then function names on public surfaces, then
enum values, then recurring words in comments and commit messages. It turns the highest-frequency
terms into glossary entries.
Each entry gets:
- A definition derived from how the code actually uses the term.
- An
_Avoid_line naming the synonyms it replaces. - A citation to the exact file it was read from.
The definitions go into GLOSSARY.md in the format domain-modeling and its sibling skills
already expect. The citations, the ambiguities and the per-term review state go into a separate
file, docs/agents/GLOSSARY-review.md, so the evidence trail is never mistaken for the vocabulary
itself.
What it replaces is a fifty-question domain interview at the start of a brownfield project: an hour of someone’s time, and the answers drift from what the code actually does anyway.
The harder problem it is built against is quieter: an agent-authored glossary that looks
confirmed is worse than no glossary at all, because later sessions treat confident-sounding prose
as settled fact. So this skill extracts rather than invents, and it marks every term UNREVIEWED
until the owner has looked at it.
That mark sits where it is visible, in a header any reader sees, because the review-state field
itself does not exist anywhere else in the plugin this feeds, and nine downstream skills load
GLOSSARY.md with no way to know the field is missing unless the header says so in prose.
When Thomas reaches for it
| What is in front of you | Reach for |
|---|---|
A brownfield repo with no GLOSSARY.md yet |
Run it at bootstrap, once, instead of an interview |
A repo that already has a GLOSSARY.md a human wrote |
Run it to add to it: leave existing entries alone, and record any contradiction as an observation under the existing entry |
| A term the code uses two incompatible ways | Let it land as AMBIGUOUS rather than guessing which reading is right |
| A domain term whose meaning cannot be read from usage | Let it land as definition: UNKNOWN with its citations rather than inventing one |
Prerequisites
Check the repo’s shape before writing anything: one bounded context gets one root GLOSSARY.md;
several contexts get a GLOSSARY-MAP.md at the root plus one GLOSSARY.md inside each context.
Seeding a single root file across a multi-context repo merges unrelated vocabularies into a
document every downstream reader treats as authoritative, and brownfield repos are the ones most
likely to be multi-context.
Read GLOSSARY-FORMAT.md first, since domain-modeling and eight other plugin skills consume
GLOSSARY.md in a fixed shape, and a code-seeded pass gets the details wrong without it.
What it leaves behind
| What happened | Where it lands |
|---|---|
| A term extracted from code, with a draft definition | GLOSSARY.md, under ## Language, marked by the file’s own header count |
| The citation, synonyms and review state for that term | docs/agents/GLOSSARY-review.md, one file regardless of how many contexts the repo has |
| A term the owner has since checked | CONFIRMED <date> in docs/agents/GLOSSARY-review.md, with the header counts in GLOSSARY.md updated to match |
| A term the code uses two incompatible ways | AMBIGUOUS in docs/agents/GLOSSARY-review.md, kept visible rather than resolved by guessing |
It’s working if
- Every entry in
GLOSSARY.mdtraces back to a real citation indocs/agents/GLOSSARY-review.md. A definition the citations do not support is the failure mode this skill is built to avoid. - The header on
GLOSSARY.mdstates the review ratio in prose a reader sees without knowing the field exists, e.g. “23 terms · 0 CONFIRMED · 21 UNREVIEWED · 2 AMBIGUOUS.” - Existing human-written entries are left untouched; anything the code contradicts is recorded as an observation, not an overwrite.
- Implementation detail and general programming concepts never make it into
GLOSSARY.md, however often the code uses them. - The owner’s review pass covers the
AMBIGUOUSterms, theUNKNOWNdefinitions and the ten highest-frequency terms first. That is the short list this skill exists to hand them, instead of a full read-through.
Where it fits
bootstrap-glossary runs once, by name, early in a brownfield project’s life, alongside the other
invoked-once, owner-reviewed bootstrap passes: extract-standards for coding conventions and
batch-triage for an inherited backlog. Thomas owns all three as phases, so none of them becomes
work everyone assumes someone else ran. Once terms are CONFIRMED, domain-modeling is where
they get sharpened further. This skill’s own job ends at handing domain-modeling a vocabulary
drawn from the code that is actually there, not one somebody guessed at in an interview.