Skip to content

Extract the glossary to a root CONTEXT.md - #10

Merged
lesnik512 merged 1 commit into
mainfrom
docs/context-glossary
Aug 23, 2026
Merged

Extract the glossary to a root CONTEXT.md#10
lesnik512 merged 1 commit into
mainfrom
docs/context-glossary

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

docs/agents/domain.md tells every skill to read a CONTEXT.md that does not
exist. The glossary it describes does exist, but as a section inside CLAUDE.md,
which no skill looks in. The consequence is not a missing file: it is that the
first /domain-modeling run to resolve a term would create a second glossary
next to the first, and this repo has already been burned by exactly that shape
once, which is why architecture/ was deleted.

This is the same move #9 made for decisions, one layer down: the content was
never the problem, only its address.

Design

Move the seven terms to a root CONTEXT.md and leave CLAUDE.md's ## Vocabulary heading in place carrying a pointer. The heading stays because
planning/README.md's deviation 2 links to it and just check-links validates
anchors; a signpost is not a duplicated fact.

Native structure, local content. The file uses the ## Language /
**Term**: / _Avoid_: shape from the skill's CONTEXT-FORMAT.md, so that
when /domain-modeling appends a term later it writes in the same style and the
file does not drift into two formats. What does not change is the definitions,
which move word for word, and the admission rule above them: a term is listed
only when there is a synonym to reject, or a meaning subtle enough that code and
docs must agree on it.

One deliberate deviation from the stock format. CONTEXT-FORMAT.md says a
definition must be one or two sentences and "totally devoid of implementation
details". Ours name direct_key, last_read_message_id and GREATEST. That is
not an oversight: this repo's admission rule turns on a term's meaning being
subtle enough that code and docs must agree, and the mechanism is usually where
that subtlety lives. Strip direct_key from Direct chat and what remains is
"a chat between two users", which no longer explains why opening one twice is an
upsert rather than a read-then-race. The precision is the reason the entry
exists.

planning/README.md's deviation 2 is repointed from ../CLAUDE.md's Vocabulary
section to ../CONTEXT.md.

Non-goals

  • Does not add, remove or reword a single term. Seven in, seven out, same
    definitions and the same Avoid lists. Only the container changed.
  • Does not touch docs/agents/domain.md. It already names CONTEXT.md and
    docs/adr/; with Convert planning/decisions to numbered ADRs in docs/adr #9 merged and this PR, both finally exist, so its consumer
    rules describe the repo as it now is rather than as it was planned to be.
  • Does not introduce CONTEXT-MAP.md. This repo is single-context, which is
    what docs/agents/domain.md states.
  • Does not record this as an ADR. Same reasoning as Convert planning/decisions to numbered ADRs in docs/adr #9: it is a decision
    about where a record lives, so this body is where it belongs.

Verification

Docs only: no Python, no configuration, no migration, no test is touched.

  • just lint passes (ruff format: 100 files unchanged; ruff check and ty check: all checks passed).
  • just check-links passes (links: OK) — the gate that matters here, since
    the change is one new file and two repointed cross-references, one of which is
    an anchor into a heading that had to survive.
  • just check-adrs passes (adr: OK), just check-planning passes (planning: OK).
  • grep confirms no "Vocabulary section" reference remains anywhere.
  • just test and just test-migrations were not run: this diff contains no
    Python and nothing either of them reads. Both passed on main at Convert planning/decisions to numbered ADRs in docs/adr #9
    (109 and 4 tests, 100% coverage) and nothing here can affect them.

@lesnik512
lesnik512 merged commit 67669f9 into main Aug 23, 2026
3 checks passed
@lesnik512
lesnik512 deleted the docs/context-glossary branch August 23, 2026 11:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant