Glossary

Glossary: Per-Project Terms & Command-Phrases

A project-local dictionary of the definitions, abbreviations, and command-phrases

that matter for *this* project. Stored in GLOSSARY.md at the project root, so

each project keeps its own. The skill definition is global; the data is

per-project — the same split as pinboard and script-registry.

Three categories:

• Definitions — variable names, dataset/database names, key concepts.

*(e.g. ret = monthly stock return; WellDatabase = the licensed well-level dataset)*

• Abbreviations — acronyms and short forms used in the project.

*(e.g. WRDS = Wharton Research Data Services)*

• Command-Phrases — phrases the user says that map to an action Claude

should perform. *(e.g. "push" = commit and push the paper to its GitHub repo)*

Definitions and abbreviations are reference — read to understand the project.

Command-phrases are behavioral — read to act.

How the glossary is used

The glossary is loaded adaptively at session start by /spin-up, so it never

weighs on the context window no matter how big it grows:

• Command-Phrases load eagerly, in full. They are behavioral and won't trigger

the skill on their own (the bare word "push" won't invoke glossary), so they

must be in context from the start. They're few by design — keep them so.

• Definitions & Abbreviations load lazily. At session start only their *term

list* (the headwords, not the glosses) is loaded, so you know what's defined.

Read the full line on demand — when one of those terms actually comes up, or

the user asks — by grepping the term in GLOSSARY.md. Do NOT pull the whole

Definitions section into context up front, and do NOT ask the user what a listed

term means — look it up.

• Small glossary? If the whole file is under ~25 entries, /spin-up just loads

it whole — the lazy split only earns its keep once the term sections grow.

On demand, always. "What does X mean?", "what does X stand for?", "what's in our

glossary?" → grep/read GLOSSARY.md and answer from it. If the term isn't there,

say so — don't guess.

Command-phrases (behavioral)

When the user uses a phrase defined under Command-Phrases, perform the mapped

action — they have already told you what they want, so don't re-ask "do you want

me to push?". But still honor standing safety rules around the action itself:

• Before any push to a public repo, run the secrets/PII preflight (scan staged

files for keys, names, usernames in paths). The command-phrase is permission to

push, not permission to skip the scan.

• Destructive or irreversible actions (delete, force-push, deploy) still get a

one-line confirmation, even when aliased.

If a command-phrase is ambiguous in the current context (e.g. "push" but there are

two repos), ask which one — briefly.

Adding entries

When explicitly asked ("add to glossary", "glossary: X means Y", "from now on

X means Y"):

• Categorise the entry — a phrase mapping to an action → Command-Phrase; an

acronym/short form → Abbreviation; anything else → Definition.

• Append silently under the right section in GLOSSARY.md. Don't reorder or

rewrite existing entries.

• Acknowledge in one line — "Added to the glossary." Don't read it back.

Proactively — *offer*, never auto-add, and only when the term clears the

inclusion bar below:

• The user defines a term in passing ("by ret I mean monthly returns") → offer:

"Want me to add ret to the glossary?"

• You hit an undefined, project-specific abbreviation or variable in their code/data

→ offer to capture it once you know what it means.

Keep offers to one line and don't nag — if declined, drop it.

What belongs (the inclusion bar)

Add a term only if it is all four: *durable* (will still matter next month),

*non-obvious* (not self-explanatory from its name), *recurring* (comes up more than

once), and *project-specific*. Same discipline as the memory system: don't store

what's derivable by reading the code.

• Belongs: ret (terse, non-obvious), WellDatabase (project dataset), "push"

(a command-phrase), a domain acronym a newcomer wouldn't know.

• Doesn't: monthly_return (self-documenting name), a one-off abbreviation used

once, anything already spelled out in README/CLAUDE.md, general-knowledge

acronyms (CSV, API).

When in doubt, leave it out — the glossary earns its always-on cost only by staying

small and high-signal.

Entry formats

One line per entry: bold headword, em-dash, then a short gloss — aim for under

~12 words. If it needs a paragraph, it belongs in README/CLAUDE.md, not here.

No timestamps. (Command-Phrases sits first because it's the only eagerly-loaded

section — see below.)

## Command-Phrases
- **"push"** — commit and push the paper to its GitHub repo

## Definitions
- **ret** — monthly stock return (CRSP, decimal)
- **WellDatabase** — licensed well-level production dataset

## Abbreviations
- **WRDS** — Wharton Research Data Services

Creating GLOSSARY.md

If it doesn't exist, create it at the project root with this structure.

Command-Phrases comes first — it's the only section loaded eagerly each session,

so keeping it at the top makes the session-start read cheap:

# Glossary

<!-- Project-specific command-phrases, definitions, and abbreviations. -->
<!-- Command-Phrases load eagerly at session start (via /spin-up); Definitions and -->
<!-- Abbreviations load lazily / on demand. Manage with /glossary. -->

## Command-Phrases

## Definitions

## Abbreviations

Add a missing section heading if needed; never drop existing entries.

Showing, editing, removing

• "Show the glossary" / "what's in our glossary" — read GLOSSARY.md and

present it by section with a count per section. If empty, say so.

• "Change X to Y" / "update the definition of X" — find the entry, edit it in

place, acknowledge in one line.

• "Remove X from glossary" — delete that entry. If it's a command-phrase, note

the alias is no longer active. Never clear the whole file without explicit

confirmation.

Keeping it lean

The glossary is always-on, so it has to stay small and high-signal.

• Size flags. /spin-up reports the counts and flags for pruning once the

glossary passes ~50 total entries or ~15 command-phrases. Treat those as

soft ceilings, not targets.

• Prune on request. "prune glossary" / "clean up the glossary" → read the file,

surface likely-dead entries (superseded command-phrases, terms that no longer

appear in the code/paper, duplicates), and propose removals. Never bulk-delete

without confirmation.

• One concept per entry. If an entry is growing into a paragraph or listing

several things, it's the wrong tool — move it to README/CLAUDE.md.

Relationship to other systems

• vs pinboard — pinboard holds transient tasks/notes/ideas that get done and

cleared; the glossary holds stable terms that persist for the project's life.

• vs memory (~/.claude/.../memory/) — memory stores cross-project facts about

the user, feedback, and project context; the glossary stores project-specific

*terms* and *phrases*, and lives inside the project.

• vs CLAUDE.md — hard project rules belong in CLAUDE.md; the glossary is the

lighter, user-editable list of what tokens mean and what phrases trigger.

Important rules

• Read GLOSSARY.md before writing it — append, don't overwrite.
• Per-project — always the GLOSSARY.md in the current project root, never a

shared global file. Repeat universal phrases like "push" in each project that

needs them.

• Don't editorialize — it's the user's dictionary; capture their wording, don't

"improve" definitions.

• Keep it readable — a human scans this. Consistent formatting, one entry per

line, no timestamps (definitions are stable; they don't age like pinboard notes).