---
name: principle-define-the-terms
description: "Apply when writing or editing prose an agent reads (a SKILL.md, CLAUDE.md or AGENTS.md, a subagent brief, a plan, a PR description), when naming a concept, or when a word in the repo is doing double duty. One term, one meaning, and a glossary that bans the synonyms it displaces."
disable-model-invocation: true
---

# Define the Terms

Prose is the weakest rung (the **encode-lessons-in-structure** principle skill). When you have to use it anyway, every term in it means one thing, and the glossary says which.

**Why:** The glossary is the shared-understanding contract between the human and the agent, not just a consistency tool; the **align-on-intent** principle skill owns the intent half of that contract. An agent cannot ask what you meant. It picks the reading it already believed and acts on it, and you find out one diff later. Ambiguity hides in the words that sound most harmless, because a word everybody uses is a word nobody has defined. `tool`, `config`, `context`, `mode`, `workflow`, `service`, `handler`, `plugin`, `component`: each of these means four things, and a rule written with one of them is four rules.

**Pattern:**

1. Before writing a rule about a concept, name the concept in one word.
2. Put it in the repo glossary (`CONTEXT.md`) with a one-line definition and an **Avoid** list of the synonyms it displaces.
3. Use that word everywhere it applies. Never cycle synonyms for variety; the unslop skill bans that as a style tell, and here it is a correctness problem.
4. A word already meaning two things in this repo gets split into two words. Both keep their own entry. Adding a qualifier to one use and leaving the other bare does not fix it, because the bare one still reads as either.

**The banned synonym is the half a mechanism can hold.** A definition tells a careful reader what you meant; a banned word is greppable. But grade the bans honestly, because most of them cannot be enforced. A word like `config file` or `tool` carries a legitimate second sense, and a check that flags every use trains everyone to skip the check. In this repository that split is `_Avoid_` for guidance and `_Never_` for a word with no second sense here, with only the second enforced by [the glossary linter](../../docs/reference/glossary-linter.md). Grading is not weakness. An unenforceable ban dressed as an enforced one is how a linter gets disabled, and a disabled linter enforces nothing at all.

Expect a waiver even on the words you were sure about. Both `_Never_` hits in this repository turned out to be legitimate second senses on first run.

**Where it matters most:** prose that agents read and cannot clarify. Skill bodies, `CLAUDE.md` and `AGENTS.md`, subagent briefs, plan and phase files, acceptance criteria. A brief whose `SCOPE` says "the auth module" fails differently for every worker that reads it; one that names paths does not.

**Anti-patterns:**

- A glossary that defines terms and then the same file uses two synonyms for one of them.
- A glossary nobody cites. If no skill, brief, or context file points at it, it is not in the loop and it will rot.
- Coining a term for a concept that appears once. A name earns its entry when the concept shows up in two places or a rule cannot be written without it (the **subtract-before-you-add** principle skill).
- Renaming a term without migrating its uses, which leaves both words live and doubles the ambiguity you set out to remove (the **converge-on-the-target** principle skill).

**Balance:** A two-file repo does not need a glossary. The trigger is a term already used two ways, or a rule you cannot state precisely without naming something first.