Shared language is the cheapest defect prevention there is. This skill keeps two
small artefacts: a GLOSSARY.md where every domain term has one name, one
definition in business language, the synonyms to avoid and an owner who settles
disputes; and a folder of short decision records for choices that are costly to
reverse, surprising later and the result of a real trade-off. Its tools pull
candidate terms out of conversations and code, lint the glossary, find banned
synonyms in docs and identifiers, and keep decision records numbered and linked.
GLOSSARY.md and docs/adr/ if presentWhat most shapes the output is whether the language is being created, repaired or checked, and who has authority over it. Settle the inputs below before producing anything. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.
Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.
# Lint the sample glossary and find banned aliases in a feature note
python3 engineering/domain-modeling/scripts/glossary_lint.py \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md \
--scan engineering/domain-modeling/assets/sample_feature_notes.md
# Lint the sample decision records and get the next file name
python3 engineering/domain-modeling/scripts/adr_lint.py \
--input engineering/domain-modeling/assets/sample_adr_set.json \
--next-title "Publish events for billing"
```bash
python3 engineering/domain-modeling/scripts/term_extract.py \
--paths engineering/domain-modeling/assets/sample_conversation.txt \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md --format text
```
pause and suspension are two concepts that need two entries; membership is an alias of Subscription.proposed and ask each owner to confirm.Exit code 1 means new candidates exist and need a decision — useful as a periodic review prompt, not a merge gate.
assets/GLOSSARY-template.md: one ### Term block per concept with Definition, Avoid, Owner, Related, Status.```bash
python3 engineering/domain-modeling/scripts/glossary_lint.py \
--glossary engineering/domain-modeling/assets/sample_GLOSSARY.md \
--scan engineering/domain-modeling/assets/samplefeaturenotes.md --format json
```
clientId and memberships.renew count as uses of "client" and "membership". Fix docs now; rename identifiers when the files are next touched.Validation checkpoint: the lint reports no errors, every term has an owner, and the scan over changed docs is clean before the glossary change merges.
The sample glossary is deliberately flawed and exits 1: a duplicate Plan, the alias Account colliding with the canonical term Account, Churn mapped to two terms, an invalid status, and an implementation-heavy definition of Charge.
--scan, and if the choice was contested, record it as a decision so it is not reopened.The agent offers a record only when a choice passes all three tests: costly to reverse, surprising without context, and a real trade-off.
adr_lint.py --dir docs/adr --next-title "<decision>".assets/adr-template.md: decisive title, Context with glossary terms, "We will…" Decision, alternatives with reasons, consequences.proposed; set accepted once deciders agree. Never edit an accepted record's decision — supersede it and add **Supersedes:** NNNN to the new one.```bash
python3 engineering/domain-modeling/scripts/adr_lint.py \
--input engineering/domain-modeling/assets/sampleadrset.json --format text
```
The sample set exits 1: number 0004 is used twice, 0002 points at a missing replacement, 0005 claims to supersede 0002 while 0002 names another record, and one record has no Decision section.
--scan on the changed paths).| Question | Yes → | No → |
|---|---|---|
| Would two people here plausibly mean different things by it? | Add it | Next question |
| Does a new hire need it explained to read tickets or code? | Add it | Next question |
| Is it generic engineering vocabulary (cache, retry, queue)? | Leave it out | — |
Split into per-context glossaries when a term keeps two definitions that both survive the scenario test, or when two teams keep correcting each other's usage. Keep a root GLOSSARY.md that lists contexts and translations, and translate explicitly at the code seam between them.
| Costly to reverse | Surprising later | Real alternative | Record? |
|---|---|---|---|
| Yes | Yes | Yes | Yes |
| Yes | No | Yes | No — the code explains it |
| No | Any | Any | No — just change it later |
| Yes | Yes | No | Usually no; a code comment suffices |
Mistake: Definitions that describe tables, flags, endpoints and retry counts ("a row in the charges table with a captured boolean").
Why it happens: Engineers write the glossary and describe what they know best — storage.
Instead: Define what the thing is in business language. Storage changes every quarter; the concept does not. glossary_lint.py warns on implementation words.
Mistake: Listing synonyms as "also known as" and accepting all of them.
Why it happens: Picking one word feels like overruling colleagues.
Instead: Choose one canonical term and list the rest under Avoid. A glossary that blesses three names has not removed any ambiguity. Let the term's owner make the call.
Mistake: Banning "churn" under both Cancellation and Downgrade, or banning a word that is itself a canonical term elsewhere.
Why it happens: Terms are added one at a time without checking the rest of the file.
Instead: Each alias maps to exactly one term. If a word genuinely covers two concepts, it is a split, not an alias — say so in both definitions. The linter rejects both collisions.
Mistake: A decision record for every library choice and folder rename, until nobody reads the folder.
Why it happens: Records feel like diligence, and writing one is easy.
Instead: Apply the three-part test. A record that fails it is noise that hides the records that matter.
Mistake: Rewriting an accepted record when the decision changes, or deleting a record that turned out wrong.
Why it happens: It keeps the folder tidy.
Instead: Supersede: write a new record, mark the old one superseded by NNNN, and add **Supersedes:** to the new one. The reasoning that was overturned is exactly what the next person needs to see.
| Script | Purpose | Exit codes |
|---|---|---|
scripts/glossary_lint.py | Lint ### Term entries (missing definition/owner, duplicates, alias collisions, circular, overlong or implementation-heavy definitions, invalid status, dangling Related); --scan finds avoided aliases in docs and code with identifier splitting | 0 clean, 1 errors or alias usages, 2 input error |
scripts/term_extract.py | Count content words and two-word phrases in transcripts, docs and code; classify as defined, avoided alias or new; list glossary terms never used | 0 no new candidates, 1 candidates need a decision, 2 input error |
scripts/adr_lint.py | Check numbering, title/file match, status values, two-way supersession links, required sections, decisive wording, recorded alternatives; --next-title prints the next file name | 0 clean, 1 errors, 2 input error |
All take --format text|json. adr_lint.py reads --dir docs/adr or a JSON bundle via --input.
| File | Purpose |
|---|---|
references/glossary-practice.md | What belongs, entry rules, extraction triage, synonym resolution order, scenario probing, multi-context glossaries, upkeep |
references/decision-records.md | Three-part test, what qualifies, layout and numbering, writing rules, lifecycle and supersession, worked examples |
assets/GLOSSARY-template.md | Starting glossary with editing rules and a worked entry |
assets/adr-template.md | Decision record template with the qualification test inline |
assets/sample_GLOSSARY.md | Billing glossary with deliberate defects — linter exits 1 |
assets/sample_feature_notes.md | Feature note and code using banned aliases — --scan reports 14 uses |
assets/sample_conversation.txt | Design-session transcript for term extraction |
assets/sample_adr_set.json | Five decision records with numbering and supersession defects — linter exits 1 |
In Scope:
Out of Scope:
Important Caveats: