glossary
Look up or update specs/glossary.md, the registry of Mathiz's first-class concepts. Use before naming a new type, table, event, API resource or UI term, and whenever a PR adds, renames, splits or remo
SKILL.md.claude/skills/glossary/SKILL.md
GitHubUpdating the glossary
specs/glossary.md exists so that each concept has one name and one
implementation. Look things up there before writing code; edit it when a
concept is added, renamed, split or retired.
Is it a first-class concept?
Add an entry only if at least one is true:
- It has its own ent schema, event type, or public Go type that other packages use.
- It appears in an API path or response, a spec, or
docs/personas.md. - Parents or kids see it as a named thing in the UI.
Not glossary material: private helpers, generic programming terms, env vars (CLAUDE.md), one-off config knobs.
Do
- Search first, including synonyms and the "Homonyms & look-alikes"
section.
grep -in "<word>" specs/glossary.mdplus a code grep for the idea, not just the word. - Reuse the existing name in new code, API fields and specs, even if you'd have picked a different word.
- Use the exact entry format in the file:
### Term, a 1–3 sentence definition (what it is plus its key invariant),**Code:**(1–3 authoritative paths),**Spec:**link, and an optional**Aka / don't call it:**line. - Put it in the right domain section, alphabetically.
- Verify every
Code:path exists (grep/ls) before committing. Fix stale paths when you move code. - Update the glossary in the same PR as the code or spec that changes the concept.
- Add a Homonyms line when your term means something else elsewhere (e.g. billing plan vs session plan).
- Map kid/parent-facing copy to its internal concept on the
Akaline (e.g. "clue" → Question) instead of renaming internals to match the UI. - Mark draft-spec concepts
(proposed, specs/NN)and drop the marker when they ship.
Don't
- Don't add a near-duplicate. If your idea is a variant of an existing concept, extend that entry (and the code) or explain the difference in both entries. Never create two entries for one idea.
- Don't write essays. Design rationale belongs in the spec; the glossary links to it.
- Don't invent identifiers. Every name in
Code:must exist in the repo. - Don't delete an entry silently when a concept is retired. Remove it in the PR that removes the code, and note the replacement on any entry that referenced it.
- Don't rename a concept in the glossary alone. A rename touches code, specs, API and docs together, or not at all.
- Don't record volatile details (counts, defaults, timeouts) unless they're an invariant. They go stale; point to the code instead.
Checklist for a PR that adds a concept
- The grep found no existing concept that already covers it.
- An entry is added in the right section, alphabetically, in the house format.
- The Homonyms section is updated if the word is overloaded.
- The
Code:paths andSpec:link resolve. - The spec and
docs/personas.md(for a user-facing concept) use the same name.